APIリファレンス¶
Wandasライブラリの主要コンポーネントと関数のAPIリファレンスです。
コアモジュール¶
コアモジュールはWandasの基本的な機能を提供します。
wandas.core
¶
Attributes¶
__all__ = ['BaseFrame']
module-attribute
¶
Classes¶
BaseFrame
¶
Bases: ABC, Generic[T]
Abstract base class for all signal frame types.
This class provides the common interface and functionality for all frame types used in signal processing. It implements basic operations like indexing, iteration, and data manipulation that are shared across all frame types.
Parameters¶
data : DaArray The signal data to process. Must be a dask array. sampling_rate : float The sampling rate of the signal in Hz. label : str, optional A label for the frame. If not provided, defaults to "unnamed_frame". metadata : dict, optional Additional metadata for the frame. operation_history : list[dict], optional History of operations performed on this frame. channel_metadata : list[ChannelMetadata | dict], optional Metadata for each channel in the frame. Can be ChannelMetadata objects or dicts that will be validated by Pydantic. previous : BaseFrame, optional The frame that this frame was derived from.
Attributes¶
sampling_rate : float The sampling rate of the signal in Hz. label : str The label of the frame. metadata : dict Additional metadata for the frame. operation_history : list[dict] History of operations performed on this frame.
Source code in wandas/core/base_frame.py
27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 | |
Attributes¶
sampling_rate = sampling_rate
instance-attribute
¶
label = label or 'unnamed_frame'
instance-attribute
¶
metadata = metadata or {}
instance-attribute
¶
operation_history = operation_history or []
instance-attribute
¶
n_channels
property
¶
Returns the number of channels.
channels
property
¶
Property to access channel metadata.
previous
property
¶
Returns the previous frame.
shape
property
¶
data
property
¶
Returns the computed data. Calculation is executed the first time this is accessed.
labels
property
¶
Get a list of all channel labels.
Functions¶
__init__(data, sampling_rate, label=None, metadata=None, operation_history=None, channel_metadata=None, previous=None)
¶
Source code in wandas/core/base_frame.py
73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 | |
get_channel(channel_idx)
¶
Get channel(s) by index.
Parameters¶
channel_idx : int or sequence of int Single channel index or sequence of channel indices. Supports negative indices (e.g., -1 for the last channel).
Returns¶
S New instance containing the selected channel(s).
Examples¶
frame.get_channel(0) # Single channel frame.get_channel([0, 2, 3]) # Multiple channels frame.get_channel((-1, -2)) # Last two channels frame.get_channel(np.array([1, 2])) # NumPy array of indices
Source code in wandas/core/base_frame.py
178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 | |
__len__()
¶
Returns the number of channels.
Source code in wandas/core/base_frame.py
221 222 223 224 225 | |
__iter__()
¶
Source code in wandas/core/base_frame.py
227 228 229 | |
__getitem__(key)
¶
Get channel(s) by index, label, or advanced indexing.
This method supports multiple indexing patterns similar to NumPy and pandas:
- Single channel by index:
frame[0] - Single channel by label:
frame["ch0"] - Slice of channels:
frame[0:3] - Multiple channels by indices:
frame[[0, 2, 5]] - Multiple channels by labels:
frame[["ch0", "ch2"]] - NumPy integer array:
frame[np.array([0, 2])] - Boolean mask:
frame[mask]where mask is a boolean array - Multidimensional indexing:
frame[0, 100:200](channel + time)
Parameters¶
key : int, str, slice, list, tuple, or ndarray - int: Single channel index (supports negative indexing) - str: Single channel label - slice: Range of channels - list[int]: Multiple channel indices - list[str]: Multiple channel labels - tuple: Multidimensional indexing (channel_key, time_key, ...) - ndarray[int]: NumPy array of channel indices - ndarray[bool]: Boolean mask for channel selection
Returns¶
S New instance containing the selected channel(s).
Raises¶
ValueError If the key length is invalid for the shape or if boolean mask length doesn't match number of channels. IndexError If the channel index is out of range. TypeError If the key type is invalid or list contains mixed types. KeyError If a channel label is not found.
Examples¶
Single channel selection¶
frame[0] # First channel frame["acc_x"] # By label frame[-1] # Last channel
Multiple channel selection¶
frame[[0, 2, 5]] # Multiple indices frame[["acc_x", "acc_z"]] # Multiple labels frame[0:3] # Slice
NumPy array indexing¶
frame[np.array([0, 2, 4])] # Integer array mask = np.array([True, False, True]) frame[mask] # Boolean mask
Time slicing (multidimensional)¶
frame[0, 100:200] # Channel 0, samples 100-200 frame[[0, 1], ::2] # Channels 0-1, every 2nd sample
Source code in wandas/core/base_frame.py
231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 | |
label2index(label)
¶
Get the index from a channel label.
Parameters¶
label : str Channel label.
Returns¶
int Corresponding index.
Raises¶
KeyError If the channel label is not found.
Source code in wandas/core/base_frame.py
450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 | |
compute()
¶
Compute and return the data. This method materializes lazily computed data into a concrete NumPy array.
Returns¶
NDArrayReal The computed data.
Raises¶
ValueError If the computed result is not a NumPy array.
Source code in wandas/core/base_frame.py
497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 | |
plot(plot_type='default', ax=None, **kwargs)
abstractmethod
¶
Plot the data
Source code in wandas/core/base_frame.py
523 524 525 526 527 528 | |
persist()
¶
Persist the data in memory
Source code in wandas/core/base_frame.py
530 531 532 533 | |
__array__(dtype=None)
¶
Implicit conversion to NumPy array
Source code in wandas/core/base_frame.py
581 582 583 584 585 586 | |
visualize_graph(filename=None)
¶
Visualize the computation graph and save it to a file.
This method creates a visual representation of the Dask computation graph. In Jupyter notebooks, it returns an IPython.display.Image object that will be displayed inline. In other environments, it saves the graph to a file and returns None.
Parameters¶
filename : str, optional Output filename for the graph image. If None, a unique filename is generated using UUID. The file is saved in the current working directory.
Returns¶
IPython.display.Image or None In Jupyter environments: Returns an IPython.display.Image object that can be displayed inline. In other environments: Returns None after saving the graph to file. Returns None if visualization fails.
Notes¶
This method requires graphviz to be installed on your system:
- Ubuntu/Debian: sudo apt-get install graphviz
- macOS: brew install graphviz
- Windows: Download from https://graphviz.org/download/
The graph displays operation names (e.g., 'normalize', 'lowpass_filter') making it easier to understand the processing pipeline.
Examples¶
import wandas as wd signal = wd.read_wav("audio.wav") processed = signal.normalize().low_pass_filter(cutoff=1000)
In Jupyter: displays graph inline¶
processed.visualize_graph()
Save to specific file¶
processed.visualize_graph("my_graph.png")
See Also¶
debug_info : Print detailed debug information about the frame
Source code in wandas/core/base_frame.py
588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 | |
__add__(other)
¶
Addition operator
Source code in wandas/core/base_frame.py
655 656 657 | |
__sub__(other)
¶
Subtraction operator
Source code in wandas/core/base_frame.py
659 660 661 | |
__mul__(other)
¶
Multiplication operator
Source code in wandas/core/base_frame.py
663 664 665 | |
__truediv__(other)
¶
Division operator
Source code in wandas/core/base_frame.py
667 668 669 | |
__pow__(other)
¶
Power operator
Source code in wandas/core/base_frame.py
671 672 673 | |
apply_operation(operation_name, **params)
¶
Apply a named operation.
Parameters¶
operation_name : str Name of the operation to apply. **params : Any Parameters to pass to the operation.
Returns¶
S A new instance with the operation applied.
Source code in wandas/core/base_frame.py
675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 | |
debug_info()
¶
Output detailed debug information
Source code in wandas/core/base_frame.py
745 746 747 748 749 750 751 752 753 | |
print_operation_history()
¶
Print the operation history to standard output in a readable format.
This method writes a human-friendly representation of the
operation_history list to stdout. Each operation is printed on its
own line with an index, the operation name (if available), and the
parameters used.
Examples¶
cf.print_operation_history() 1: normalize {} 2: low_pass_filter {'cutoff': 1000}
Source code in wandas/core/base_frame.py
755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 | |
to_numpy()
¶
Convert the frame data to a NumPy array.
This method computes the Dask array and returns it as a concrete NumPy array. The returned array has the same shape as the frame's data.
Returns¶
T NumPy array containing the frame data.
Examples¶
cf = ChannelFrame.read_wav("audio.wav") data = cf.to_numpy() print(f"Shape: {data.shape}") # (n_channels, n_samples)
Source code in wandas/core/base_frame.py
782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 | |
to_tensor(framework='torch', device=None)
¶
Convert the Dask array to a tensor in the specified framework.
Parameters¶
framework : str, default="torch" The ML framework to use ("torch" or "tensorflow"). device : str or None, optional Device to place the tensor on. For PyTorch, use "cpu", "cuda", "cuda:0", etc. For TensorFlow, use "/CPU:0", "/GPU:0", etc. If None, uses the default device.
Returns¶
torch.Tensor or tf.Tensor A tensor in the specified framework.
Raises¶
ImportError If the specified framework is not installed. ValueError If the framework is not supported. TypeError If self.data is not a Dask array.
Examples¶
PyTorch tensor on CPU¶
tensor = frame.to_tensor(framework="torch", device="cpu")
PyTorch tensor on GPU¶
tensor = frame.to_tensor(framework="torch", device="cuda:0")
TensorFlow tensor on GPU¶
tensor = frame.to_tensor(framework="tensorflow", device="/GPU:0")
Source code in wandas/core/base_frame.py
801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 | |
to_dataframe()
¶
Convert the frame data to a pandas DataFrame.
This method provides a common implementation for converting frame data to pandas DataFrame. Subclasses can override this method for custom behavior.
Returns¶
pd.DataFrame DataFrame with appropriate index and columns.
Examples¶
cf = ChannelFrame.read_wav("audio.wav") df = cf.to_dataframe() print(df.head())
Source code in wandas/core/base_frame.py
906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 | |
Modules¶
base_frame
¶
Attributes¶
logger = logging.getLogger(__name__)
module-attribute
¶
T = TypeVar('T', NDArrayComplex, NDArrayReal)
module-attribute
¶
S = TypeVar('S', bound='BaseFrame[Any]')
module-attribute
¶
Classes¶
BaseFrame
¶
Bases: ABC, Generic[T]
Abstract base class for all signal frame types.
This class provides the common interface and functionality for all frame types used in signal processing. It implements basic operations like indexing, iteration, and data manipulation that are shared across all frame types.
Parameters¶
data : DaArray The signal data to process. Must be a dask array. sampling_rate : float The sampling rate of the signal in Hz. label : str, optional A label for the frame. If not provided, defaults to "unnamed_frame". metadata : dict, optional Additional metadata for the frame. operation_history : list[dict], optional History of operations performed on this frame. channel_metadata : list[ChannelMetadata | dict], optional Metadata for each channel in the frame. Can be ChannelMetadata objects or dicts that will be validated by Pydantic. previous : BaseFrame, optional The frame that this frame was derived from.
Attributes¶
sampling_rate : float The sampling rate of the signal in Hz. label : str The label of the frame. metadata : dict Additional metadata for the frame. operation_history : list[dict] History of operations performed on this frame.
Source code in wandas/core/base_frame.py
27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 | |
sampling_rate = sampling_rate
instance-attribute
¶ label = label or 'unnamed_frame'
instance-attribute
¶ metadata = metadata or {}
instance-attribute
¶ operation_history = operation_history or []
instance-attribute
¶ n_channels
property
¶Returns the number of channels.
channels
property
¶Property to access channel metadata.
previous
property
¶Returns the previous frame.
shape
property
¶ data
property
¶Returns the computed data. Calculation is executed the first time this is accessed.
labels
property
¶Get a list of all channel labels.
__init__(data, sampling_rate, label=None, metadata=None, operation_history=None, channel_metadata=None, previous=None)
¶Source code in wandas/core/base_frame.py
73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 | |
get_channel(channel_idx)
¶Get channel(s) by index.
Parameters¶
channel_idx : int or sequence of int Single channel index or sequence of channel indices. Supports negative indices (e.g., -1 for the last channel).
Returns¶
S New instance containing the selected channel(s).
Examples¶
frame.get_channel(0) # Single channel frame.get_channel([0, 2, 3]) # Multiple channels frame.get_channel((-1, -2)) # Last two channels frame.get_channel(np.array([1, 2])) # NumPy array of indices
Source code in wandas/core/base_frame.py
178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 | |
__len__()
¶Returns the number of channels.
Source code in wandas/core/base_frame.py
221 222 223 224 225 | |
__iter__()
¶Source code in wandas/core/base_frame.py
227 228 229 | |
__getitem__(key)
¶Get channel(s) by index, label, or advanced indexing.
This method supports multiple indexing patterns similar to NumPy and pandas:
- Single channel by index:
frame[0] - Single channel by label:
frame["ch0"] - Slice of channels:
frame[0:3] - Multiple channels by indices:
frame[[0, 2, 5]] - Multiple channels by labels:
frame[["ch0", "ch2"]] - NumPy integer array:
frame[np.array([0, 2])] - Boolean mask:
frame[mask]where mask is a boolean array - Multidimensional indexing:
frame[0, 100:200](channel + time)
Parameters¶
key : int, str, slice, list, tuple, or ndarray - int: Single channel index (supports negative indexing) - str: Single channel label - slice: Range of channels - list[int]: Multiple channel indices - list[str]: Multiple channel labels - tuple: Multidimensional indexing (channel_key, time_key, ...) - ndarray[int]: NumPy array of channel indices - ndarray[bool]: Boolean mask for channel selection
Returns¶
S New instance containing the selected channel(s).
Raises¶
ValueError If the key length is invalid for the shape or if boolean mask length doesn't match number of channels. IndexError If the channel index is out of range. TypeError If the key type is invalid or list contains mixed types. KeyError If a channel label is not found.
Examples¶
Single channel selection¶
frame[0] # First channel frame["acc_x"] # By label frame[-1] # Last channel
Multiple channel selection¶
frame[[0, 2, 5]] # Multiple indices frame[["acc_x", "acc_z"]] # Multiple labels frame[0:3] # Slice
NumPy array indexing¶
frame[np.array([0, 2, 4])] # Integer array mask = np.array([True, False, True]) frame[mask] # Boolean mask
Time slicing (multidimensional)¶
frame[0, 100:200] # Channel 0, samples 100-200 frame[[0, 1], ::2] # Channels 0-1, every 2nd sample
Source code in wandas/core/base_frame.py
231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 | |
label2index(label)
¶Get the index from a channel label.
Parameters¶
label : str Channel label.
Returns¶
int Corresponding index.
Raises¶
KeyError If the channel label is not found.
Source code in wandas/core/base_frame.py
450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 | |
compute()
¶Compute and return the data. This method materializes lazily computed data into a concrete NumPy array.
Returns¶
NDArrayReal The computed data.
Raises¶
ValueError If the computed result is not a NumPy array.
Source code in wandas/core/base_frame.py
497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 | |
plot(plot_type='default', ax=None, **kwargs)
abstractmethod
¶Plot the data
Source code in wandas/core/base_frame.py
523 524 525 526 527 528 | |
persist()
¶Persist the data in memory
Source code in wandas/core/base_frame.py
530 531 532 533 | |
__array__(dtype=None)
¶Implicit conversion to NumPy array
Source code in wandas/core/base_frame.py
581 582 583 584 585 586 | |
visualize_graph(filename=None)
¶Visualize the computation graph and save it to a file.
This method creates a visual representation of the Dask computation graph. In Jupyter notebooks, it returns an IPython.display.Image object that will be displayed inline. In other environments, it saves the graph to a file and returns None.
Parameters¶
filename : str, optional Output filename for the graph image. If None, a unique filename is generated using UUID. The file is saved in the current working directory.
Returns¶
IPython.display.Image or None In Jupyter environments: Returns an IPython.display.Image object that can be displayed inline. In other environments: Returns None after saving the graph to file. Returns None if visualization fails.
Notes¶
This method requires graphviz to be installed on your system:
- Ubuntu/Debian: sudo apt-get install graphviz
- macOS: brew install graphviz
- Windows: Download from https://graphviz.org/download/
The graph displays operation names (e.g., 'normalize', 'lowpass_filter') making it easier to understand the processing pipeline.
Examples¶
import wandas as wd signal = wd.read_wav("audio.wav") processed = signal.normalize().low_pass_filter(cutoff=1000)
In Jupyter: displays graph inline¶
processed.visualize_graph()
Save to specific file¶
processed.visualize_graph("my_graph.png")
See Also¶
debug_info : Print detailed debug information about the frame
Source code in wandas/core/base_frame.py
588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 | |
__add__(other)
¶Addition operator
Source code in wandas/core/base_frame.py
655 656 657 | |
__sub__(other)
¶Subtraction operator
Source code in wandas/core/base_frame.py
659 660 661 | |
__mul__(other)
¶Multiplication operator
Source code in wandas/core/base_frame.py
663 664 665 | |
__truediv__(other)
¶Division operator
Source code in wandas/core/base_frame.py
667 668 669 | |
__pow__(other)
¶Power operator
Source code in wandas/core/base_frame.py
671 672 673 | |
apply_operation(operation_name, **params)
¶Apply a named operation.
Parameters¶
operation_name : str Name of the operation to apply. **params : Any Parameters to pass to the operation.
Returns¶
S A new instance with the operation applied.
Source code in wandas/core/base_frame.py
675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 | |
debug_info()
¶Output detailed debug information
Source code in wandas/core/base_frame.py
745 746 747 748 749 750 751 752 753 | |
print_operation_history()
¶Print the operation history to standard output in a readable format.
This method writes a human-friendly representation of the
operation_history list to stdout. Each operation is printed on its
own line with an index, the operation name (if available), and the
parameters used.
Examples¶
cf.print_operation_history() 1: normalize {} 2: low_pass_filter {'cutoff': 1000}
Source code in wandas/core/base_frame.py
755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 | |
to_numpy()
¶Convert the frame data to a NumPy array.
This method computes the Dask array and returns it as a concrete NumPy array. The returned array has the same shape as the frame's data.
Returns¶
T NumPy array containing the frame data.
Examples¶
cf = ChannelFrame.read_wav("audio.wav") data = cf.to_numpy() print(f"Shape: {data.shape}") # (n_channels, n_samples)
Source code in wandas/core/base_frame.py
782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 | |
to_tensor(framework='torch', device=None)
¶Convert the Dask array to a tensor in the specified framework.
Parameters¶
framework : str, default="torch" The ML framework to use ("torch" or "tensorflow"). device : str or None, optional Device to place the tensor on. For PyTorch, use "cpu", "cuda", "cuda:0", etc. For TensorFlow, use "/CPU:0", "/GPU:0", etc. If None, uses the default device.
Returns¶
torch.Tensor or tf.Tensor A tensor in the specified framework.
Raises¶
ImportError If the specified framework is not installed. ValueError If the framework is not supported. TypeError If self.data is not a Dask array.
Examples¶
PyTorch tensor on CPU¶
tensor = frame.to_tensor(framework="torch", device="cpu")
PyTorch tensor on GPU¶
tensor = frame.to_tensor(framework="torch", device="cuda:0")
TensorFlow tensor on GPU¶
tensor = frame.to_tensor(framework="tensorflow", device="/GPU:0")
Source code in wandas/core/base_frame.py
801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 | |
to_dataframe()
¶Convert the frame data to a pandas DataFrame.
This method provides a common implementation for converting frame data to pandas DataFrame. Subclasses can override this method for custom behavior.
Returns¶
pd.DataFrame DataFrame with appropriate index and columns.
Examples¶
cf = ChannelFrame.read_wav("audio.wav") df = cf.to_dataframe() print(df.head())
Source code in wandas/core/base_frame.py
906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 | |
metadata
¶
Classes¶
ChannelMetadata
¶
Bases: BaseModel
Data class for storing channel metadata
Source code in wandas/core/metadata.py
8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 | |
label = ''
class-attribute
instance-attribute
¶ unit = ''
class-attribute
instance-attribute
¶ ref = 1.0
class-attribute
instance-attribute
¶ extra = Field(default_factory=dict)
class-attribute
instance-attribute
¶ label_value
property
¶Get the label value
unit_value
property
¶Get the unit value
ref_value
property
¶Get the ref value
extra_data
property
¶Get the extra metadata dictionary
__init__(**data)
¶Source code in wandas/core/metadata.py
19 20 21 22 23 | |
__setattr__(name, value)
¶Override setattr to update ref when unit is changed directly
Source code in wandas/core/metadata.py
25 26 27 28 29 30 | |
__getitem__(key)
¶Provide dictionary-like behavior
Source code in wandas/core/metadata.py
52 53 54 55 56 57 58 59 60 61 | |
__setitem__(key, value)
¶Provide dictionary-like behavior
Source code in wandas/core/metadata.py
63 64 65 66 67 68 69 70 71 72 73 | |
to_json()
¶Convert to JSON format
Source code in wandas/core/metadata.py
75 76 77 78 | |
from_json(json_data)
classmethod
¶Convert from JSON format
Source code in wandas/core/metadata.py
80 81 82 83 84 85 | |
Functions¶
フレームモジュール¶
フレームモジュールは異なるタイプのデータフレームを定義します。
wandas.frames
¶
Frame classes for wandas.
Attributes¶
__all__ = ['ChannelFrame', 'RoughnessFrame']
module-attribute
¶
Classes¶
ChannelFrame
¶
Bases: BaseFrame[NDArrayReal], ChannelProcessingMixin, ChannelTransformMixin
Channel-based data frame for handling audio signals and time series data.
This frame represents channel-based data such as audio signals and time series data, with each channel containing data samples in the time domain.
Source code in wandas/frames/channel.py
37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 | |
Attributes¶
time
property
¶
Get time array for the signal.
The time array represents the start time of each sample, calculated as sample_index / sampling_rate. This provides a uniform, evenly-spaced time axis that is consistent across all frame types in wandas.
For frames resulting from windowed analysis operations (e.g., FFT, loudness, roughness), each time point corresponds to the start of the analysis window, not the center. This differs from some libraries (e.g., MoSQITo) which use window center times, but does not affect the calculated values themselves.
Returns:
| Type | Description |
|---|---|
NDArrayReal
|
Array of time points in seconds, starting from 0.0. |
Examples:
>>> import wandas as wd
>>> signal = wd.read_wav("audio.wav")
>>> time = signal.time
>>> print(f"Duration: {time[-1]:.3f}s")
>>> print(f"Time step: {time[1] - time[0]:.6f}s")
n_samples
property
¶
Returns the number of samples.
duration
property
¶
Returns the duration in seconds.
rms
property
¶
Calculate RMS (Root Mean Square) value for each channel.
Returns:
| Type | Description |
|---|---|
NDArrayReal
|
Array of RMS values, one per channel. |
Examples:
>>> cf = ChannelFrame.read_wav("audio.wav")
>>> rms_values = cf.rms
>>> print(f"RMS values: {rms_values}")
>>> # Select channels with RMS > threshold
>>> active_channels = cf[cf.rms > 0.5]
Functions¶
__init__(data, sampling_rate, label=None, metadata=None, operation_history=None, channel_metadata=None, previous=None)
¶
Initialize a ChannelFrame.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
Array
|
Dask array containing channel data. |
required |
sampling_rate
|
float
|
The sampling rate of the data in Hz. Must be a positive value. |
required |
label
|
str | None
|
A label for the frame. |
None
|
metadata
|
dict[str, Any] | None
|
Optional metadata dictionary. |
None
|
operation_history
|
list[dict[str, Any]] | None
|
History of operations applied to the frame. |
None
|
channel_metadata
|
list[ChannelMetadata] | list[dict[str, Any]] | None
|
Metadata for each channel. |
None
|
previous
|
Optional[BaseFrame[Any]]
|
Reference to the previous frame in the processing chain. |
None
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If data has more than 2 dimensions, or if sampling_rate is not positive. |
Source code in wandas/frames/channel.py
46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 | |
info()
¶
Display comprehensive information about the ChannelFrame.
This method prints a summary of the frame's properties including: - Number of channels - Sampling rate - Duration - Number of samples - Channel labels
This is a convenience method to view all key properties at once, similar to pandas DataFrame.info().
Examples¶
cf = ChannelFrame.read_wav("audio.wav") cf.info() Channels: 2 Sampling rate: 44100 Hz Duration: 1.0 s Samples: 44100 Channel labels: ['ch0', 'ch1']
Source code in wandas/frames/channel.py
161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 | |
add(other, snr=None)
¶
Add another signal or value to the current signal.
If SNR is specified, performs addition with consideration for signal-to-noise ratio.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
other
|
ChannelFrame | int | float | NDArrayReal
|
Signal or value to add. |
required |
snr
|
float | None
|
Signal-to-noise ratio (dB). If specified, adjusts the scale of the other signal based on this SNR. self is treated as the signal, and other as the noise. |
None
|
Returns:
| Type | Description |
|---|---|
ChannelFrame
|
A new channel frame containing the addition result (lazy execution). |
Source code in wandas/frames/channel.py
331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 | |
plot(plot_type='waveform', ax=None, title=None, overlay=False, xlabel=None, ylabel=None, alpha=1.0, xlim=None, ylim=None, **kwargs)
¶
Plot the frame data.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
plot_type
|
str
|
Type of plot. Default is "waveform". |
'waveform'
|
ax
|
Optional[Axes]
|
Optional matplotlib axes for plotting. |
None
|
title
|
str | None
|
Title for the plot. If None, uses the frame label. |
None
|
overlay
|
bool
|
Whether to overlay all channels on a single plot (True) or create separate subplots for each channel (False). |
False
|
xlabel
|
str | None
|
Label for the x-axis. If None, uses default based on plot type. |
None
|
ylabel
|
str | None
|
Label for the y-axis. If None, uses default based on plot type. |
None
|
alpha
|
float
|
Transparency level for the plot lines (0.0 to 1.0). |
1.0
|
xlim
|
tuple[float, float] | None
|
Limits for the x-axis as (min, max) tuple. |
None
|
ylim
|
tuple[float, float] | None
|
Limits for the y-axis as (min, max) tuple. |
None
|
**kwargs
|
Any
|
Additional matplotlib Line2D parameters (e.g., color, linewidth, linestyle). These are passed to the underlying matplotlib plot functions. |
{}
|
Returns:
| Type | Description |
|---|---|
Axes | Iterator[Axes]
|
Single Axes object or iterator of Axes objects. |
Examples:
>>> cf = ChannelFrame.read_wav("audio.wav")
>>> # Basic plot
>>> cf.plot()
>>> # Overlay all channels
>>> cf.plot(overlay=True, alpha=0.7)
>>> # Custom styling
>>> cf.plot(title="My Signal", ylabel="Voltage [V]", color="red")
Source code in wandas/frames/channel.py
382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 | |
rms_plot(ax=None, title=None, overlay=True, Aw=False, **kwargs)
¶
Generate an RMS plot.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ax
|
Optional[Axes]
|
Optional matplotlib axes for plotting. |
None
|
title
|
str | None
|
Title for the plot. |
None
|
overlay
|
bool
|
Whether to overlay the plot on the existing axis. |
True
|
Aw
|
bool
|
Apply A-weighting. |
False
|
**kwargs
|
Any
|
Additional arguments passed to the plot() method. Accepts the same arguments as plot() including xlabel, ylabel, alpha, xlim, ylim, and matplotlib Line2D parameters. |
{}
|
Returns:
| Type | Description |
|---|---|
Axes | Iterator[Axes]
|
Single Axes object or iterator of Axes objects. |
Examples:
>>> cf = ChannelFrame.read_wav("audio.wav")
>>> # Basic RMS plot
>>> cf.rms_plot()
>>> # With A-weighting
>>> cf.rms_plot(Aw=True)
>>> # Custom styling
>>> cf.rms_plot(ylabel="RMS [V]", alpha=0.8, color="blue")
Source code in wandas/frames/channel.py
455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 | |
describe(normalize=True, is_close=True, *, fmin=0, fmax=None, cmap='jet', vmin=None, vmax=None, xlim=None, ylim=None, Aw=False, waveform=None, spectral=None, **kwargs)
¶
Display visual and audio representation of the frame.
This method creates a comprehensive visualization with three plots: 1. Time-domain waveform (top) 2. Spectrogram (bottom-left) 3. Frequency spectrum via Welch method (bottom-right)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
normalize
|
bool
|
Whether to normalize the audio data for playback. Default: True |
True
|
is_close
|
bool
|
Whether to close the figure after displaying. Default: True |
True
|
fmin
|
float
|
Minimum frequency to display in the spectrogram (Hz). Default: 0 |
0
|
fmax
|
float | None
|
Maximum frequency to display in the spectrogram (Hz). Default: Nyquist frequency (sampling_rate / 2) |
None
|
cmap
|
str
|
Colormap for the spectrogram. Default: 'jet' |
'jet'
|
vmin
|
float | None
|
Minimum value for spectrogram color scale (dB). Auto-calculated if None. |
None
|
vmax
|
float | None
|
Maximum value for spectrogram color scale (dB). Auto-calculated if None. |
None
|
xlim
|
tuple[float, float] | None
|
Time axis limits (seconds) for all time-based plots. Format: (start_time, end_time) |
None
|
ylim
|
tuple[float, float] | None
|
Frequency axis limits (Hz) for frequency-based plots. Format: (min_freq, max_freq) |
None
|
Aw
|
bool
|
Apply A-weighting to the frequency analysis. Default: False |
False
|
waveform
|
dict[str, Any] | None
|
Additional configuration dict for waveform subplot. Can include 'xlabel', 'ylabel', 'xlim', 'ylim'. |
None
|
spectral
|
dict[str, Any] | None
|
Additional configuration dict for spectral subplot. Can include 'xlabel', 'ylabel', 'xlim', 'ylim'. |
None
|
**kwargs
|
Any
|
Deprecated parameters for backward compatibility only. - axis_config: Old configuration format (use waveform/spectral instead) - cbar_config: Old colorbar configuration (use vmin/vmax instead) |
{}
|
Examples:
>>> cf = ChannelFrame.read_wav("audio.wav")
>>> # Basic usage
>>> cf.describe()
>>>
>>> # Custom frequency range
>>> cf.describe(fmin=100, fmax=5000)
>>>
>>> # Custom color scale
>>> cf.describe(vmin=-80, vmax=-20, cmap="viridis")
>>>
>>> # A-weighted analysis
>>> cf.describe(Aw=True)
>>>
>>> # Custom time range
>>> cf.describe(xlim=(0, 5)) # Show first 5 seconds
>>>
>>> # Custom waveform subplot settings
>>> cf.describe(waveform={"ylabel": "Custom Label"})
Source code in wandas/frames/channel.py
491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 | |
from_numpy(data, sampling_rate, label=None, metadata=None, ch_labels=None, ch_units=None)
classmethod
¶
Create a ChannelFrame from a NumPy array.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
NDArrayReal
|
NumPy array containing channel data. |
required |
sampling_rate
|
float
|
The sampling rate in Hz. |
required |
label
|
str | None
|
A label for the frame. |
None
|
metadata
|
dict[str, Any] | None
|
Optional metadata dictionary. |
None
|
ch_labels
|
list[str] | None
|
Labels for each channel. |
None
|
ch_units
|
list[str] | str | None
|
Units for each channel. |
None
|
Returns:
| Type | Description |
|---|---|
ChannelFrame
|
A new ChannelFrame containing the NumPy data. |
Source code in wandas/frames/channel.py
625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 | |
from_ndarray(array, sampling_rate, labels=None, unit=None, frame_label=None, metadata=None)
classmethod
¶
Create a ChannelFrame from a NumPy array.
This method is deprecated. Use from_numpy instead.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
array
|
NDArrayReal
|
Signal data. Each row corresponds to a channel. |
required |
sampling_rate
|
float
|
Sampling rate (Hz). |
required |
labels
|
list[str] | None
|
Labels for each channel. |
None
|
unit
|
list[str] | str | None
|
Unit of the signal. |
None
|
frame_label
|
str | None
|
Label for the frame. |
None
|
metadata
|
dict[str, Any] | None
|
Optional metadata dictionary. |
None
|
Returns:
| Type | Description |
|---|---|
ChannelFrame
|
A new ChannelFrame containing the data. |
Source code in wandas/frames/channel.py
686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 | |
from_file(path, channel=None, start=None, end=None, ch_labels=None, time_column=0, delimiter=',', header=0)
classmethod
¶
Create a ChannelFrame from an audio file.
Note
The chunk_size parameter has been removed. ChannelFrame uses
channel-wise chunking by default (chunks=(1, -1)). Use .rechunk(...)
on the returned frame for custom sample-axis chunking.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | Path
|
Path to the audio file. |
required |
channel
|
int | list[int] | None
|
Channel(s) to load. None loads all channels. |
None
|
start
|
float | None
|
Start time in seconds. |
None
|
end
|
float | None
|
End time in seconds. |
None
|
ch_labels
|
list[str] | None
|
Labels for each channel. |
None
|
time_column
|
int | str
|
For CSV files, index or name of the time column. Default is 0 (first column). |
0
|
delimiter
|
str
|
For CSV files, delimiter character. Default is ",". |
','
|
header
|
int | None
|
For CSV files, row number to use as header. Default is 0 (first row). Set to None if no header. |
0
|
Returns:
| Type | Description |
|---|---|
ChannelFrame
|
A new ChannelFrame containing the loaded audio data. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If channel specification is invalid or file cannot be read. Error message includes absolute path, current directory, and troubleshooting suggestions. |
Examples:
>>> # Load WAV file
>>> cf = ChannelFrame.from_file("audio.wav")
>>> # Load specific channels
>>> cf = ChannelFrame.from_file("audio.wav", channel=[0, 2])
>>> # Load CSV file
>>> cf = ChannelFrame.from_file(
... "data.csv", time_column=0, delimiter=",", header=0
... )
Source code in wandas/frames/channel.py
723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 | |
read_wav(filename, labels=None)
classmethod
¶
Utility method to read a WAV file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filename
|
str
|
Path to the WAV file. |
required |
labels
|
list[str] | None
|
Labels to set for each channel. |
None
|
Returns:
| Type | Description |
|---|---|
ChannelFrame
|
A new ChannelFrame containing the data (lazy loading). |
Source code in wandas/frames/channel.py
897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 | |
read_csv(filename, time_column=0, labels=None, delimiter=',', header=0)
classmethod
¶
Utility method to read a CSV file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filename
|
str
|
Path to the CSV file. |
required |
time_column
|
int | str
|
Index or name of the time column. |
0
|
labels
|
list[str] | None
|
Labels to set for each channel. |
None
|
delimiter
|
str
|
Delimiter character. |
','
|
header
|
int | None
|
Row number to use as header. |
0
|
Returns:
| Type | Description |
|---|---|
ChannelFrame
|
A new ChannelFrame containing the data (lazy loading). |
Examples:
>>> # Read CSV with default settings
>>> cf = ChannelFrame.read_csv("data.csv")
>>> # Read CSV with custom delimiter
>>> cf = ChannelFrame.read_csv("data.csv", delimiter=";")
>>> # Read CSV without header
>>> cf = ChannelFrame.read_csv("data.csv", header=None)
Source code in wandas/frames/channel.py
913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 | |
to_wav(path, format=None)
¶
Save the audio data to a WAV file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | Path
|
Path to save the file. |
required |
format
|
str | None
|
File format. If None, determined from file extension. |
None
|
Source code in wandas/frames/channel.py
953 954 955 956 957 958 959 960 961 962 | |
save(path, *, format='hdf5', compress='gzip', overwrite=False, dtype=None)
¶
Save the ChannelFrame to a WDF (Wandas Data File) format.
This saves the complete frame including all channel data and metadata in a format that can be loaded back with full fidelity.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | Path
|
Path to save the file. '.wdf' extension will be added if not present. |
required |
format
|
str
|
Format to use (currently only 'hdf5' is supported) |
'hdf5'
|
compress
|
str | None
|
Compression method ('gzip' by default, None for no compression) |
'gzip'
|
overwrite
|
bool
|
Whether to overwrite existing file |
False
|
dtype
|
str | dtype[Any] | None
|
Optional data type conversion before saving (e.g. 'float32') |
None
|
Raises:
| Type | Description |
|---|---|
FileExistsError
|
If the file exists and overwrite=False. |
NotImplementedError
|
For unsupported formats. |
Example
cf = ChannelFrame.read_wav("audio.wav") cf.save("audio_analysis.wdf")
Source code in wandas/frames/channel.py
964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 | |
load(path, *, format='hdf5')
classmethod
¶
Load a ChannelFrame from a WDF (Wandas Data File) file.
This loads data saved with the save() method, preserving all channel data, metadata, labels, and units.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | Path
|
Path to the WDF file |
required |
format
|
str
|
Format of the file (currently only 'hdf5' is supported) |
'hdf5'
|
Returns:
| Type | Description |
|---|---|
ChannelFrame
|
A new ChannelFrame with all data and metadata loaded |
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
If the file doesn't exist |
NotImplementedError
|
For unsupported formats |
Example
cf = ChannelFrame.load("audio_analysis.wdf")
Source code in wandas/frames/channel.py
1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 | |
add_channel(data, label=None, align='strict', suffix_on_dup=None, inplace=False)
¶
Add a new channel to the frame.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
ndarray[Any, Any] | Array | ChannelFrame
|
Data to add as a new channel. Can be: - numpy array (1D or 2D) - dask array (1D or 2D) - ChannelFrame (channels will be added) |
required |
label
|
str | None
|
Label for the new channel. If None, generates a default label. Ignored when data is a ChannelFrame (uses its channel labels). |
None
|
align
|
str
|
How to handle length mismatches: - "strict": Raise error if lengths don't match - "pad": Pad shorter data with zeros - "truncate": Truncate longer data to match |
'strict'
|
suffix_on_dup
|
str | None
|
Suffix to add to duplicate labels. If None, raises error. |
None
|
inplace
|
bool
|
If True, modifies the frame in place. Otherwise returns a new frame. |
False
|
Returns:
| Type | Description |
|---|---|
ChannelFrame
|
Modified ChannelFrame (self if inplace=True, new frame otherwise). |
Raises:
| Type | Description |
|---|---|
ValueError
|
If data length doesn't match and align="strict", or if label is duplicate and suffix_on_dup is None. |
TypeError
|
If data type is not supported. |
Examples:
>>> cf = ChannelFrame.read_wav("audio.wav")
>>> # Add a numpy array as a new channel
>>> new_data = np.sin(2 * np.pi * 440 * cf.time)
>>> cf_new = cf.add_channel(new_data, label="sine_440Hz")
>>> # Add another ChannelFrame's channels
>>> cf2 = ChannelFrame.read_wav("audio2.wav")
>>> cf_combined = cf.add_channel(cf2)
Source code in wandas/frames/channel.py
1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 | |
remove_channel(key, inplace=False)
¶
Source code in wandas/frames/channel.py
1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 | |
RoughnessFrame
¶
Bases: BaseFrame[NDArrayReal]
Frame for detailed roughness analysis with Bark-band information.
This frame contains specific roughness (R_spec) data organized by Bark frequency bands over time, calculated using the Daniel & Weber (1997) method.
The relationship between total roughness and specific roughness follows: R = 0.25 * sum(R_spec, axis=bark_bands)
Parameters¶
data : da.Array Specific roughness data with shape: - (n_bark_bands, n_time) for mono signals - (n_channels, n_bark_bands, n_time) for multi-channel signals where n_bark_bands is always 47. sampling_rate : float Sampling rate of the roughness time series in Hz. For overlap=0.5, this is approximately 10 Hz (100ms hop). For overlap=0.0, this is approximately 5 Hz (200ms hop). bark_axis : NDArrayReal Bark frequency axis with 47 values from 0.5 to 23.5 Bark. overlap : float Overlap coefficient used in the calculation (0.0 to 1.0). label : str, optional Frame label. Defaults to "roughness_spec". metadata : dict, optional Additional metadata. operation_history : list[dict], optional History of operations applied to this frame. channel_metadata : list[ChannelMetadata], optional Metadata for each channel. previous : BaseFrame, optional Reference to the previous frame in the processing chain.
Attributes¶
bark_axis : NDArrayReal Frequency axis in Bark scale. n_bark_bands : int Number of Bark bands (always 47). n_time_points : int Number of time points. time : NDArrayReal Time axis based on sampling rate. overlap : float Overlap coefficient used (0.0 to 1.0).
Examples¶
Create a roughness frame from a signal:
import wandas as wd signal = wd.read_wav("motor.wav") roughness_spec = signal.roughness_dw_spec(overlap=0.5)
Plot Bark-Time heatmap¶
roughness_spec.plot()
Find dominant Bark band¶
dominant_idx = roughness_spec.data.mean(axis=1).argmax() dominant_bark = roughness_spec.bark_axis[dominant_idx] print(f"Dominant frequency: {dominant_bark:.1f} Bark")
Extract specific Bark band¶
bark_10_idx = np.argmin(np.abs(roughness_spec.bark_axis - 10.0)) roughness_at_10bark = roughness_spec.data[bark_10_idx, :]
Notes¶
The Daniel & Weber (1997) roughness model calculates specific roughness for 47 critical bands (Bark scale) over time, then integrates them to produce the total roughness:
.. math:: R = 0.25 \sum_{i=1}^{47} R'_i
where R'_i is the specific roughness in the i-th Bark band.
References¶
.. [1] Daniel, P., & Weber, R. (1997). "Psychoacoustical roughness: Implementation of an optimized model". Acta Acustica united with Acustica, 83(1), 113-123.
Source code in wandas/frames/roughness.py
22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 | |
Attributes¶
data
property
¶
Returns the computed data without squeezing.
For RoughnessFrame, even mono signals have 2D shape (47, n_time) so we don't squeeze the channel dimension.
Returns¶
NDArrayReal Computed data array.
bark_axis
property
¶
n_time_points
property
¶
Number of time points in the roughness time series.
Returns¶
int Number of time frames in the analysis.
time
property
¶
overlap
property
¶
Functions¶
__init__(data, sampling_rate, bark_axis, overlap, label=None, metadata=None, operation_history=None, channel_metadata=None, previous=None)
¶
Initialize a RoughnessFrame.
Source code in wandas/frames/roughness.py
110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 | |
to_dataframe()
¶
DataFrame conversion is not supported for RoughnessFrame.
RoughnessFrame contains 3D data (channels, bark_bands, time_frames) which cannot be directly converted to a 2D DataFrame.
Raises¶
NotImplementedError Always raised as DataFrame conversion is not supported.
Source code in wandas/frames/roughness.py
274 275 276 277 278 279 280 281 282 283 284 285 286 287 | |
plot(plot_type='heatmap', ax=None, title=None, cmap='viridis', vmin=None, vmax=None, xlabel='Time [s]', ylabel='Frequency [Bark]', colorbar_label='Specific Roughness [Asper/Bark]', **kwargs)
¶
Plot Bark-Time-Roughness heatmap.
For multi-channel signals, the mean across channels is plotted.
Parameters¶
ax : Axes, optional Matplotlib axes to plot on. If None, a new figure is created. title : str, optional Plot title. If None, a default title is used. cmap : str, default="viridis" Colormap name for the heatmap. vmin, vmax : float, optional Color scale limits. If None, automatic scaling is used. xlabel : str, default="Time [s]" Label for the x-axis. ylabel : str, default="Frequency [Bark]" Label for the y-axis. colorbar_label : str, default="Specific Roughness [Asper/Bark]" Label for the colorbar. **kwargs : Any Additional keyword arguments passed to pcolormesh.
Returns¶
Axes The matplotlib axes object containing the plot.
Examples¶
import wandas as wd signal = wd.read_wav("motor.wav") roughness_spec = signal.roughness_dw_spec(overlap=0.5) roughness_spec.plot(cmap="hot", title="Motor Roughness Analysis")
Source code in wandas/frames/roughness.py
401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 | |
Modules¶
channel
¶
Attributes¶
logger = logging.getLogger(__name__)
module-attribute
¶
dask_delayed = dask.delayed
module-attribute
¶
da_from_delayed = da.from_delayed
module-attribute
¶
S = TypeVar('S', bound='BaseFrame[Any]')
module-attribute
¶
Classes¶
ChannelFrame
¶
Bases: BaseFrame[NDArrayReal], ChannelProcessingMixin, ChannelTransformMixin
Channel-based data frame for handling audio signals and time series data.
This frame represents channel-based data such as audio signals and time series data, with each channel containing data samples in the time domain.
Source code in wandas/frames/channel.py
37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 | |
time
property
¶Get time array for the signal.
The time array represents the start time of each sample, calculated as sample_index / sampling_rate. This provides a uniform, evenly-spaced time axis that is consistent across all frame types in wandas.
For frames resulting from windowed analysis operations (e.g., FFT, loudness, roughness), each time point corresponds to the start of the analysis window, not the center. This differs from some libraries (e.g., MoSQITo) which use window center times, but does not affect the calculated values themselves.
Returns:
| Type | Description |
|---|---|
NDArrayReal
|
Array of time points in seconds, starting from 0.0. |
Examples:
>>> import wandas as wd
>>> signal = wd.read_wav("audio.wav")
>>> time = signal.time
>>> print(f"Duration: {time[-1]:.3f}s")
>>> print(f"Time step: {time[1] - time[0]:.6f}s")
n_samples
property
¶Returns the number of samples.
duration
property
¶Returns the duration in seconds.
rms
property
¶Calculate RMS (Root Mean Square) value for each channel.
Returns:
| Type | Description |
|---|---|
NDArrayReal
|
Array of RMS values, one per channel. |
Examples:
>>> cf = ChannelFrame.read_wav("audio.wav")
>>> rms_values = cf.rms
>>> print(f"RMS values: {rms_values}")
>>> # Select channels with RMS > threshold
>>> active_channels = cf[cf.rms > 0.5]
__init__(data, sampling_rate, label=None, metadata=None, operation_history=None, channel_metadata=None, previous=None)
¶Initialize a ChannelFrame.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
Array
|
Dask array containing channel data. |
required |
sampling_rate
|
float
|
The sampling rate of the data in Hz. Must be a positive value. |
required |
label
|
str | None
|
A label for the frame. |
None
|
metadata
|
dict[str, Any] | None
|
Optional metadata dictionary. |
None
|
operation_history
|
list[dict[str, Any]] | None
|
History of operations applied to the frame. |
None
|
channel_metadata
|
list[ChannelMetadata] | list[dict[str, Any]] | None
|
Metadata for each channel. |
None
|
previous
|
Optional[BaseFrame[Any]]
|
Reference to the previous frame in the processing chain. |
None
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If data has more than 2 dimensions, or if sampling_rate is not positive. |
Source code in wandas/frames/channel.py
46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 | |
info()
¶Display comprehensive information about the ChannelFrame.
This method prints a summary of the frame's properties including: - Number of channels - Sampling rate - Duration - Number of samples - Channel labels
This is a convenience method to view all key properties at once, similar to pandas DataFrame.info().
Examples¶
cf = ChannelFrame.read_wav("audio.wav") cf.info() Channels: 2 Sampling rate: 44100 Hz Duration: 1.0 s Samples: 44100 Channel labels: ['ch0', 'ch1']
Source code in wandas/frames/channel.py
161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 | |
add(other, snr=None)
¶Add another signal or value to the current signal.
If SNR is specified, performs addition with consideration for signal-to-noise ratio.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
other
|
ChannelFrame | int | float | NDArrayReal
|
Signal or value to add. |
required |
snr
|
float | None
|
Signal-to-noise ratio (dB). If specified, adjusts the scale of the other signal based on this SNR. self is treated as the signal, and other as the noise. |
None
|
Returns:
| Type | Description |
|---|---|
ChannelFrame
|
A new channel frame containing the addition result (lazy execution). |
Source code in wandas/frames/channel.py
331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 | |
plot(plot_type='waveform', ax=None, title=None, overlay=False, xlabel=None, ylabel=None, alpha=1.0, xlim=None, ylim=None, **kwargs)
¶Plot the frame data.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
plot_type
|
str
|
Type of plot. Default is "waveform". |
'waveform'
|
ax
|
Optional[Axes]
|
Optional matplotlib axes for plotting. |
None
|
title
|
str | None
|
Title for the plot. If None, uses the frame label. |
None
|
overlay
|
bool
|
Whether to overlay all channels on a single plot (True) or create separate subplots for each channel (False). |
False
|
xlabel
|
str | None
|
Label for the x-axis. If None, uses default based on plot type. |
None
|
ylabel
|
str | None
|
Label for the y-axis. If None, uses default based on plot type. |
None
|
alpha
|
float
|
Transparency level for the plot lines (0.0 to 1.0). |
1.0
|
xlim
|
tuple[float, float] | None
|
Limits for the x-axis as (min, max) tuple. |
None
|
ylim
|
tuple[float, float] | None
|
Limits for the y-axis as (min, max) tuple. |
None
|
**kwargs
|
Any
|
Additional matplotlib Line2D parameters (e.g., color, linewidth, linestyle). These are passed to the underlying matplotlib plot functions. |
{}
|
Returns:
| Type | Description |
|---|---|
Axes | Iterator[Axes]
|
Single Axes object or iterator of Axes objects. |
Examples:
>>> cf = ChannelFrame.read_wav("audio.wav")
>>> # Basic plot
>>> cf.plot()
>>> # Overlay all channels
>>> cf.plot(overlay=True, alpha=0.7)
>>> # Custom styling
>>> cf.plot(title="My Signal", ylabel="Voltage [V]", color="red")
Source code in wandas/frames/channel.py
382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 | |
rms_plot(ax=None, title=None, overlay=True, Aw=False, **kwargs)
¶Generate an RMS plot.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ax
|
Optional[Axes]
|
Optional matplotlib axes for plotting. |
None
|
title
|
str | None
|
Title for the plot. |
None
|
overlay
|
bool
|
Whether to overlay the plot on the existing axis. |
True
|
Aw
|
bool
|
Apply A-weighting. |
False
|
**kwargs
|
Any
|
Additional arguments passed to the plot() method. Accepts the same arguments as plot() including xlabel, ylabel, alpha, xlim, ylim, and matplotlib Line2D parameters. |
{}
|
Returns:
| Type | Description |
|---|---|
Axes | Iterator[Axes]
|
Single Axes object or iterator of Axes objects. |
Examples:
>>> cf = ChannelFrame.read_wav("audio.wav")
>>> # Basic RMS plot
>>> cf.rms_plot()
>>> # With A-weighting
>>> cf.rms_plot(Aw=True)
>>> # Custom styling
>>> cf.rms_plot(ylabel="RMS [V]", alpha=0.8, color="blue")
Source code in wandas/frames/channel.py
455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 | |
describe(normalize=True, is_close=True, *, fmin=0, fmax=None, cmap='jet', vmin=None, vmax=None, xlim=None, ylim=None, Aw=False, waveform=None, spectral=None, **kwargs)
¶Display visual and audio representation of the frame.
This method creates a comprehensive visualization with three plots: 1. Time-domain waveform (top) 2. Spectrogram (bottom-left) 3. Frequency spectrum via Welch method (bottom-right)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
normalize
|
bool
|
Whether to normalize the audio data for playback. Default: True |
True
|
is_close
|
bool
|
Whether to close the figure after displaying. Default: True |
True
|
fmin
|
float
|
Minimum frequency to display in the spectrogram (Hz). Default: 0 |
0
|
fmax
|
float | None
|
Maximum frequency to display in the spectrogram (Hz). Default: Nyquist frequency (sampling_rate / 2) |
None
|
cmap
|
str
|
Colormap for the spectrogram. Default: 'jet' |
'jet'
|
vmin
|
float | None
|
Minimum value for spectrogram color scale (dB). Auto-calculated if None. |
None
|
vmax
|
float | None
|
Maximum value for spectrogram color scale (dB). Auto-calculated if None. |
None
|
xlim
|
tuple[float, float] | None
|
Time axis limits (seconds) for all time-based plots. Format: (start_time, end_time) |
None
|
ylim
|
tuple[float, float] | None
|
Frequency axis limits (Hz) for frequency-based plots. Format: (min_freq, max_freq) |
None
|
Aw
|
bool
|
Apply A-weighting to the frequency analysis. Default: False |
False
|
waveform
|
dict[str, Any] | None
|
Additional configuration dict for waveform subplot. Can include 'xlabel', 'ylabel', 'xlim', 'ylim'. |
None
|
spectral
|
dict[str, Any] | None
|
Additional configuration dict for spectral subplot. Can include 'xlabel', 'ylabel', 'xlim', 'ylim'. |
None
|
**kwargs
|
Any
|
Deprecated parameters for backward compatibility only. - axis_config: Old configuration format (use waveform/spectral instead) - cbar_config: Old colorbar configuration (use vmin/vmax instead) |
{}
|
Examples:
>>> cf = ChannelFrame.read_wav("audio.wav")
>>> # Basic usage
>>> cf.describe()
>>>
>>> # Custom frequency range
>>> cf.describe(fmin=100, fmax=5000)
>>>
>>> # Custom color scale
>>> cf.describe(vmin=-80, vmax=-20, cmap="viridis")
>>>
>>> # A-weighted analysis
>>> cf.describe(Aw=True)
>>>
>>> # Custom time range
>>> cf.describe(xlim=(0, 5)) # Show first 5 seconds
>>>
>>> # Custom waveform subplot settings
>>> cf.describe(waveform={"ylabel": "Custom Label"})
Source code in wandas/frames/channel.py
491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 | |
from_numpy(data, sampling_rate, label=None, metadata=None, ch_labels=None, ch_units=None)
classmethod
¶Create a ChannelFrame from a NumPy array.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
NDArrayReal
|
NumPy array containing channel data. |
required |
sampling_rate
|
float
|
The sampling rate in Hz. |
required |
label
|
str | None
|
A label for the frame. |
None
|
metadata
|
dict[str, Any] | None
|
Optional metadata dictionary. |
None
|
ch_labels
|
list[str] | None
|
Labels for each channel. |
None
|
ch_units
|
list[str] | str | None
|
Units for each channel. |
None
|
Returns:
| Type | Description |
|---|---|
ChannelFrame
|
A new ChannelFrame containing the NumPy data. |
Source code in wandas/frames/channel.py
625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 | |
from_ndarray(array, sampling_rate, labels=None, unit=None, frame_label=None, metadata=None)
classmethod
¶Create a ChannelFrame from a NumPy array.
This method is deprecated. Use from_numpy instead.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
array
|
NDArrayReal
|
Signal data. Each row corresponds to a channel. |
required |
sampling_rate
|
float
|
Sampling rate (Hz). |
required |
labels
|
list[str] | None
|
Labels for each channel. |
None
|
unit
|
list[str] | str | None
|
Unit of the signal. |
None
|
frame_label
|
str | None
|
Label for the frame. |
None
|
metadata
|
dict[str, Any] | None
|
Optional metadata dictionary. |
None
|
Returns:
| Type | Description |
|---|---|
ChannelFrame
|
A new ChannelFrame containing the data. |
Source code in wandas/frames/channel.py
686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 | |
from_file(path, channel=None, start=None, end=None, ch_labels=None, time_column=0, delimiter=',', header=0)
classmethod
¶Create a ChannelFrame from an audio file.
Note
The chunk_size parameter has been removed. ChannelFrame uses
channel-wise chunking by default (chunks=(1, -1)). Use .rechunk(...)
on the returned frame for custom sample-axis chunking.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | Path
|
Path to the audio file. |
required |
channel
|
int | list[int] | None
|
Channel(s) to load. None loads all channels. |
None
|
start
|
float | None
|
Start time in seconds. |
None
|
end
|
float | None
|
End time in seconds. |
None
|
ch_labels
|
list[str] | None
|
Labels for each channel. |
None
|
time_column
|
int | str
|
For CSV files, index or name of the time column. Default is 0 (first column). |
0
|
delimiter
|
str
|
For CSV files, delimiter character. Default is ",". |
','
|
header
|
int | None
|
For CSV files, row number to use as header. Default is 0 (first row). Set to None if no header. |
0
|
Returns:
| Type | Description |
|---|---|
ChannelFrame
|
A new ChannelFrame containing the loaded audio data. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If channel specification is invalid or file cannot be read. Error message includes absolute path, current directory, and troubleshooting suggestions. |
Examples:
>>> # Load WAV file
>>> cf = ChannelFrame.from_file("audio.wav")
>>> # Load specific channels
>>> cf = ChannelFrame.from_file("audio.wav", channel=[0, 2])
>>> # Load CSV file
>>> cf = ChannelFrame.from_file(
... "data.csv", time_column=0, delimiter=",", header=0
... )
Source code in wandas/frames/channel.py
723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 | |
read_wav(filename, labels=None)
classmethod
¶Utility method to read a WAV file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filename
|
str
|
Path to the WAV file. |
required |
labels
|
list[str] | None
|
Labels to set for each channel. |
None
|
Returns:
| Type | Description |
|---|---|
ChannelFrame
|
A new ChannelFrame containing the data (lazy loading). |
Source code in wandas/frames/channel.py
897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 | |
read_csv(filename, time_column=0, labels=None, delimiter=',', header=0)
classmethod
¶Utility method to read a CSV file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filename
|
str
|
Path to the CSV file. |
required |
time_column
|
int | str
|
Index or name of the time column. |
0
|
labels
|
list[str] | None
|
Labels to set for each channel. |
None
|
delimiter
|
str
|
Delimiter character. |
','
|
header
|
int | None
|
Row number to use as header. |
0
|
Returns:
| Type | Description |
|---|---|
ChannelFrame
|
A new ChannelFrame containing the data (lazy loading). |
Examples:
>>> # Read CSV with default settings
>>> cf = ChannelFrame.read_csv("data.csv")
>>> # Read CSV with custom delimiter
>>> cf = ChannelFrame.read_csv("data.csv", delimiter=";")
>>> # Read CSV without header
>>> cf = ChannelFrame.read_csv("data.csv", header=None)
Source code in wandas/frames/channel.py
913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 | |
to_wav(path, format=None)
¶Save the audio data to a WAV file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | Path
|
Path to save the file. |
required |
format
|
str | None
|
File format. If None, determined from file extension. |
None
|
Source code in wandas/frames/channel.py
953 954 955 956 957 958 959 960 961 962 | |
save(path, *, format='hdf5', compress='gzip', overwrite=False, dtype=None)
¶Save the ChannelFrame to a WDF (Wandas Data File) format.
This saves the complete frame including all channel data and metadata in a format that can be loaded back with full fidelity.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | Path
|
Path to save the file. '.wdf' extension will be added if not present. |
required |
format
|
str
|
Format to use (currently only 'hdf5' is supported) |
'hdf5'
|
compress
|
str | None
|
Compression method ('gzip' by default, None for no compression) |
'gzip'
|
overwrite
|
bool
|
Whether to overwrite existing file |
False
|
dtype
|
str | dtype[Any] | None
|
Optional data type conversion before saving (e.g. 'float32') |
None
|
Raises:
| Type | Description |
|---|---|
FileExistsError
|
If the file exists and overwrite=False. |
NotImplementedError
|
For unsupported formats. |
Example
cf = ChannelFrame.read_wav("audio.wav") cf.save("audio_analysis.wdf")
Source code in wandas/frames/channel.py
964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 | |
load(path, *, format='hdf5')
classmethod
¶Load a ChannelFrame from a WDF (Wandas Data File) file.
This loads data saved with the save() method, preserving all channel data, metadata, labels, and units.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | Path
|
Path to the WDF file |
required |
format
|
str
|
Format of the file (currently only 'hdf5' is supported) |
'hdf5'
|
Returns:
| Type | Description |
|---|---|
ChannelFrame
|
A new ChannelFrame with all data and metadata loaded |
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
If the file doesn't exist |
NotImplementedError
|
For unsupported formats |
Example
cf = ChannelFrame.load("audio_analysis.wdf")
Source code in wandas/frames/channel.py
1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 | |
add_channel(data, label=None, align='strict', suffix_on_dup=None, inplace=False)
¶Add a new channel to the frame.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
ndarray[Any, Any] | Array | ChannelFrame
|
Data to add as a new channel. Can be: - numpy array (1D or 2D) - dask array (1D or 2D) - ChannelFrame (channels will be added) |
required |
label
|
str | None
|
Label for the new channel. If None, generates a default label. Ignored when data is a ChannelFrame (uses its channel labels). |
None
|
align
|
str
|
How to handle length mismatches: - "strict": Raise error if lengths don't match - "pad": Pad shorter data with zeros - "truncate": Truncate longer data to match |
'strict'
|
suffix_on_dup
|
str | None
|
Suffix to add to duplicate labels. If None, raises error. |
None
|
inplace
|
bool
|
If True, modifies the frame in place. Otherwise returns a new frame. |
False
|
Returns:
| Type | Description |
|---|---|
ChannelFrame
|
Modified ChannelFrame (self if inplace=True, new frame otherwise). |
Raises:
| Type | Description |
|---|---|
ValueError
|
If data length doesn't match and align="strict", or if label is duplicate and suffix_on_dup is None. |
TypeError
|
If data type is not supported. |
Examples:
>>> cf = ChannelFrame.read_wav("audio.wav")
>>> # Add a numpy array as a new channel
>>> new_data = np.sin(2 * np.pi * 440 * cf.time)
>>> cf_new = cf.add_channel(new_data, label="sine_440Hz")
>>> # Add another ChannelFrame's channels
>>> cf2 = ChannelFrame.read_wav("audio2.wav")
>>> cf_combined = cf.add_channel(cf2)
Source code in wandas/frames/channel.py
1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 | |
remove_channel(key, inplace=False)
¶Source code in wandas/frames/channel.py
1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 | |
Functions¶
mixins
¶
Channel frame mixins module.
Attributes¶
__all__ = ['ChannelProcessingMixin', 'ChannelTransformMixin']
module-attribute
¶
Classes¶
ChannelProcessingMixin
¶
Mixin that provides methods related to signal processing.
This mixin provides processing methods applied to audio signals and other time-series data, such as signal processing filters and transformation operations.
Source code in wandas/frames/mixins/channel_processing_mixin.py
25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 | |
high_pass_filter(cutoff, order=4)
¶Apply a high-pass filter to the signal.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cutoff
|
float
|
Filter cutoff frequency (Hz) |
required |
order
|
int
|
Filter order. Default is 4. |
4
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame after filter application |
Source code in wandas/frames/mixins/channel_processing_mixin.py
33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 | |
low_pass_filter(cutoff, order=4)
¶Apply a low-pass filter to the signal.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cutoff
|
float
|
Filter cutoff frequency (Hz) |
required |
order
|
int
|
Filter order. Default is 4. |
4
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame after filter application |
Source code in wandas/frames/mixins/channel_processing_mixin.py
51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 | |
band_pass_filter(low_cutoff, high_cutoff, order=4)
¶Apply a band-pass filter to the signal.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
low_cutoff
|
float
|
Lower cutoff frequency (Hz) |
required |
high_cutoff
|
float
|
Higher cutoff frequency (Hz) |
required |
order
|
int
|
Filter order. Default is 4. |
4
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame after filter application |
Source code in wandas/frames/mixins/channel_processing_mixin.py
69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 | |
normalize(norm=float('inf'), axis=-1, threshold=None, fill=None)
¶Normalize signal levels using librosa.util.normalize.
This method normalizes the signal amplitude according to the specified norm.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
norm
|
float | None
|
Norm type. Default is np.inf (maximum absolute value normalization). Supported values: - np.inf: Maximum absolute value normalization - -np.inf: Minimum absolute value normalization - 0: Peak normalization - float: Lp norm - None: No normalization |
float('inf')
|
axis
|
int | None
|
Axis along which to normalize. Default is -1 (time axis). - -1: Normalize along time axis (each channel independently) - None: Global normalization across all axes - int: Normalize along specified axis |
-1
|
threshold
|
float | None
|
Threshold below which values are considered zero. If None, no threshold is applied. |
None
|
fill
|
bool | None
|
Value to fill when the norm is zero. If None, the zero vector remains zero. |
None
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame containing the normalized signal |
Examples:
>>> import wandas as wd
>>> signal = wd.read_wav("audio.wav")
>>> # Normalize to maximum absolute value of 1.0 (per channel)
>>> normalized = signal.normalize()
>>> # Global normalization across all channels
>>> normalized_global = signal.normalize(axis=None)
>>> # L2 normalization
>>> normalized_l2 = signal.normalize(norm=2)
Source code in wandas/frames/mixins/channel_processing_mixin.py
94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 | |
remove_dc()
¶Remove DC component (DC offset) from the signal.
This method removes the DC (direct current) component by subtracting the mean value from each channel. This is equivalent to centering the signal around zero.
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame with DC component removed |
Examples:
>>> import wandas as wd
>>> import numpy as np
>>> # Create signal with DC offset
>>> signal = wd.read_wav("audio.wav")
>>> signal_with_dc = signal + 2.0 # Add DC offset
>>> # Remove DC offset
>>> signal_clean = signal_with_dc.remove_dc()
>>> # Verify DC removal
>>> assert np.allclose(signal_clean.data.mean(axis=1), 0, atol=1e-10)
Notes
- This operation is performed per channel
- Equivalent to applying a high-pass filter with very low cutoff
- Useful for removing sensor drift or measurement offset
Source code in wandas/frames/mixins/channel_processing_mixin.py
144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 | |
a_weighting()
¶Apply A-weighting filter to the signal.
A-weighting adjusts the frequency response to approximate human auditory perception, according to the IEC 61672-1:2013 standard.
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame containing the A-weighted signal |
Source code in wandas/frames/mixins/channel_processing_mixin.py
174 175 176 177 178 179 180 181 182 183 184 | |
abs()
¶Compute the absolute value of the signal.
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame containing the absolute values |
Source code in wandas/frames/mixins/channel_processing_mixin.py
186 187 188 189 190 191 192 193 | |
power(exponent=2.0)
¶Compute the power of the signal.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
exponent
|
float
|
Exponent to raise the signal to. Default is 2.0. |
2.0
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame containing the powered signal |
Source code in wandas/frames/mixins/channel_processing_mixin.py
195 196 197 198 199 200 201 202 203 204 205 | |
sum()
¶Sum all channels.
Returns:
| Type | Description |
|---|---|
T_Processing
|
A new ChannelFrame with summed signal. |
Source code in wandas/frames/mixins/channel_processing_mixin.py
245 246 247 248 249 250 251 | |
mean()
¶Average all channels.
Returns:
| Type | Description |
|---|---|
T_Processing
|
A new ChannelFrame with averaged signal. |
Source code in wandas/frames/mixins/channel_processing_mixin.py
253 254 255 256 257 258 259 | |
trim(start=0, end=None)
¶Trim the signal to the specified time range.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
start
|
float
|
Start time (seconds) |
0
|
end
|
float | None
|
End time (seconds) |
None
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame containing the trimmed signal |
Raises:
| Type | Description |
|---|---|
ValueError
|
If end time is earlier than start time |
Source code in wandas/frames/mixins/channel_processing_mixin.py
261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 | |
fix_length(length=None, duration=None)
¶Adjust the signal to the specified length.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
duration
|
float | None
|
Signal length in seconds |
None
|
length
|
int | None
|
Signal length in samples |
None
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame containing the adjusted signal |
Source code in wandas/frames/mixins/channel_processing_mixin.py
285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 | |
rms_trend(frame_length=2048, hop_length=512, dB=False, Aw=False)
¶Compute the RMS trend of the signal.
This method calculates the root mean square value over a sliding window.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
frame_length
|
int
|
Size of the sliding window in samples. Default is 2048. |
2048
|
hop_length
|
int
|
Hop length between windows in samples. Default is 512. |
512
|
dB
|
bool
|
Whether to return RMS values in decibels. Default is False. |
False
|
Aw
|
bool
|
Whether to apply A-weighting. Default is False. |
False
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame containing the RMS trend |
Source code in wandas/frames/mixins/channel_processing_mixin.py
303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 | |
channel_difference(other_channel=0)
¶Compute the difference between channels.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
other_channel
|
int | str
|
Index or label of the reference channel. Default is 0. |
0
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame containing the channel difference |
Source code in wandas/frames/mixins/channel_processing_mixin.py
343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 | |
resampling(target_sr, **kwargs)
¶Resample audio data.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target_sr
|
float
|
Target sampling rate (Hz) |
required |
**kwargs
|
Any
|
Additional resampling parameters |
{}
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
Resampled ChannelFrame |
Source code in wandas/frames/mixins/channel_processing_mixin.py
362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 | |
hpss_harmonic(kernel_size=31, power=2, margin=1, n_fft=2048, hop_length=None, win_length=None, window='hann', center=True, pad_mode='constant')
¶Extract harmonic components using HPSS (Harmonic-Percussive Source Separation).
This method separates the harmonic (tonal) components from the signal.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
kernel_size
|
Union[_IntLike_co, tuple[_IntLike_co, _IntLike_co], list[_IntLike_co]]
|
Median filter size for HPSS. |
31
|
power
|
float
|
Exponent for the Weiner filter used in HPSS. |
2
|
margin
|
Union[_FloatLike_co, tuple[_FloatLike_co, _FloatLike_co], list[_FloatLike_co]]
|
Margin size for the separation. |
1
|
n_fft
|
int
|
Size of FFT window. |
2048
|
hop_length
|
int | None
|
Hop length for STFT. |
None
|
win_length
|
int | None
|
Window length for STFT. |
None
|
window
|
_WindowSpec
|
Window type for STFT. |
'hann'
|
center
|
bool
|
If True, center the frames. |
True
|
pad_mode
|
_PadModeSTFT
|
Padding mode for STFT. |
'constant'
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
A new ChannelFrame containing the harmonic components. |
Source code in wandas/frames/mixins/channel_processing_mixin.py
385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 | |
hpss_percussive(kernel_size=31, power=2, margin=1, n_fft=2048, hop_length=None, win_length=None, window='hann', center=True, pad_mode='constant')
¶Extract percussive components using HPSS (Harmonic-Percussive Source Separation).
This method separates the percussive (tonal) components from the signal.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
kernel_size
|
Union[_IntLike_co, tuple[_IntLike_co, _IntLike_co], list[_IntLike_co]]
|
Median filter size for HPSS. |
31
|
power
|
float
|
Exponent for the Weiner filter used in HPSS. |
2
|
margin
|
Union[_FloatLike_co, tuple[_FloatLike_co, _FloatLike_co], list[_FloatLike_co]]
|
Margin size for the separation. |
1
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
A new ChannelFrame containing the harmonic components. |
Source code in wandas/frames/mixins/channel_processing_mixin.py
437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 | |
loudness_zwtv(field_type='free')
¶Calculate time-varying loudness using Zwicker method (ISO 532-1:2017).
This method computes the loudness of non-stationary signals according to the Zwicker method, as specified in ISO 532-1:2017. The loudness is calculated in sones, where a doubling of sones corresponds to a doubling of perceived loudness.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
field_type
|
str
|
Type of sound field. Options: - 'free': Free field (sound from a specific direction) - 'diffuse': Diffuse field (sound from all directions) Default is 'free'. |
'free'
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame containing time-varying loudness values in sones. |
T_Processing
|
Each channel is processed independently. |
T_Processing
|
The output sampling rate is adjusted based on the loudness |
T_Processing
|
calculation time resolution (typically ~500 Hz for 2ms steps). |
Raises:
| Type | Description |
|---|---|
ValueError
|
If field_type is not 'free' or 'diffuse' |
Examples:
Calculate loudness for a signal:
>>> import wandas as wd
>>> signal = wd.read_wav("audio.wav")
>>> loudness = signal.loudness_zwtv(field_type="free")
>>> loudness.plot(title="Time-varying Loudness")
Compare free field and diffuse field:
>>> loudness_free = signal.loudness_zwtv(field_type="free")
>>> loudness_diffuse = signal.loudness_zwtv(field_type="diffuse")
Notes
- The output contains time-varying loudness values in sones
- Typical loudness: 1 sone ≈ 40 phon (loudness level)
- The time resolution is approximately 2ms (determined by the algorithm)
- For multi-channel signals, loudness is calculated per channel
- The output sampling rate is updated to reflect the time resolution
Time axis convention: The time axis in the returned frame represents the start time of each 2ms analysis step. This differs slightly from the MoSQITo library, which uses the center time of each step. For example:
- wandas time: [0.000s, 0.002s, 0.004s, ...] (step start)
- MoSQITo time: [0.001s, 0.003s, 0.005s, ...] (step center)
The difference is very small (~1ms) and does not affect the loudness values themselves. This design choice ensures consistency with wandas's time axis convention across all frame types.
References
ISO 532-1:2017, "Acoustics — Methods for calculating loudness — Part 1: Zwicker method"
Source code in wandas/frames/mixins/channel_processing_mixin.py
483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 | |
loudness_zwst(field_type='free')
¶Calculate steady-state loudness using Zwicker method (ISO 532-1:2017).
This method computes the loudness of stationary (steady) signals according to the Zwicker method, as specified in ISO 532-1:2017. The loudness is calculated in sones, where a doubling of sones corresponds to a doubling of perceived loudness.
This method is suitable for analyzing steady sounds such as fan noise, constant machinery sounds, or other stationary signals.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
field_type
|
str
|
Type of sound field. Options: - 'free': Free field (sound from a specific direction) - 'diffuse': Diffuse field (sound from all directions) Default is 'free'. |
'free'
|
Returns:
| Type | Description |
|---|---|
NDArrayReal
|
Loudness values in sones, one per channel. Shape: (n_channels,) |
Raises:
| Type | Description |
|---|---|
ValueError
|
If field_type is not 'free' or 'diffuse' |
Examples:
Calculate steady-state loudness for a fan noise:
>>> import wandas as wd
>>> signal = wd.read_wav("fan_noise.wav")
>>> loudness = signal.loudness_zwst(field_type="free")
>>> print(f"Channel 0 loudness: {loudness[0]:.2f} sones")
>>> print(f"Mean loudness: {loudness.mean():.2f} sones")
Compare free field and diffuse field:
>>> loudness_free = signal.loudness_zwst(field_type="free")
>>> loudness_diffuse = signal.loudness_zwst(field_type="diffuse")
>>> print(f"Free field: {loudness_free[0]:.2f} sones")
>>> print(f"Diffuse field: {loudness_diffuse[0]:.2f} sones")
Notes
- Returns a 1D array with one loudness value per channel
- Typical loudness: 1 sone ≈ 40 phon (loudness level)
- For multi-channel signals, loudness is calculated independently per channel
- This method is designed for stationary signals (constant sounds)
- For time-varying signals, use loudness_zwtv() instead
- Similar to the rms property, returns NDArrayReal for consistency
References
ISO 532-1:2017, "Acoustics — Methods for calculating loudness — Part 1: Zwicker method"
Source code in wandas/frames/mixins/channel_processing_mixin.py
546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 | |
roughness_dw(overlap=0.5)
¶Calculate time-varying roughness using Daniel and Weber method.
Roughness is a psychoacoustic metric that quantifies the perceived harshness or roughness of a sound, measured in asper. This method implements the Daniel & Weber (1997) standard calculation.
The calculation follows the standard formula: R = 0.25 * sum(R'_i) for i=1 to 47 Bark bands
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
overlap
|
float
|
Overlapping coefficient for 200ms analysis windows (0.0 to 1.0). - overlap=0.5: 100ms hop → ~10 Hz output sampling rate - overlap=0.0: 200ms hop → ~5 Hz output sampling rate Default is 0.5. |
0.5
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame containing time-varying roughness values in asper. |
T_Processing
|
The output sampling rate depends on the overlap parameter. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If overlap is not in the range [0.0, 1.0] |
Examples:
Calculate roughness for a motor noise:
>>> import wandas as wd
>>> signal = wd.read_wav("motor_noise.wav")
>>> roughness = signal.roughness_dw(overlap=0.5)
>>> roughness.plot(ylabel="Roughness [asper]")
Analyze roughness statistics:
>>> mean_roughness = roughness.data.mean()
>>> max_roughness = roughness.data.max()
>>> print(f"Mean: {mean_roughness:.2f} asper")
>>> print(f"Max: {max_roughness:.2f} asper")
Compare before and after modification:
>>> before = wd.read_wav("motor_before.wav").roughness_dw()
>>> after = wd.read_wav("motor_after.wav").roughness_dw()
>>> improvement = before.data.mean() - after.data.mean()
>>> print(f"Roughness reduction: {improvement:.2f} asper")
Notes
- Returns a ChannelFrame with time-varying roughness values
- Typical roughness values: 0-2 asper for most sounds
- Higher values indicate rougher, harsher sounds
- For multi-channel signals, roughness is calculated independently per channel
- This is the standard-compliant total roughness (R)
- For detailed Bark-band analysis, use roughness_dw_spec() instead
Time axis convention: The time axis in the returned frame represents the start time of each 200ms analysis window. This differs from the MoSQITo library, which uses the center time of each window. For example:
- wandas time: [0.0s, 0.1s, 0.2s, ...] (window start)
- MoSQITo time: [0.1s, 0.2s, 0.3s, ...] (window center)
The difference is constant (half the window duration = 100ms) and does not affect the roughness values themselves. This design choice ensures consistency with wandas's time axis convention across all frame types.
References
Daniel, P., & Weber, R. (1997). "Psychoacoustical roughness: Implementation of an optimized model." Acustica, 83, 113-123.
Source code in wandas/frames/mixins/channel_processing_mixin.py
623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 | |
roughness_dw_spec(overlap=0.5)
¶Calculate specific roughness with Bark-band frequency information.
This method returns detailed roughness analysis data organized by Bark frequency bands over time, allowing for frequency-specific roughness analysis. It uses the Daniel & Weber (1997) method.
The relationship between total roughness and specific roughness: R = 0.25 * sum(R'_i) for i=1 to 47 Bark bands
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
overlap
|
float
|
Overlapping coefficient for 200ms analysis windows (0.0 to 1.0). - overlap=0.5: 100ms hop → ~10 Hz output sampling rate - overlap=0.0: 200ms hop → ~5 Hz output sampling rate Default is 0.5. |
0.5
|
Returns:
| Type | Description |
|---|---|
RoughnessFrame
|
RoughnessFrame containing: - data: Specific roughness by Bark band, shape (47, n_time) for mono or (n_channels, 47, n_time) for multi-channel - bark_axis: Frequency axis in Bark scale (47 values, 0.5-23.5) - time: Time axis for each analysis frame - overlap: Overlap coefficient used - plot(): Method for Bark-Time heatmap visualization |
Raises:
| Type | Description |
|---|---|
ValueError
|
If overlap is not in the range [0.0, 1.0] |
Examples:
Analyze frequency-specific roughness:
>>> import wandas as wd
>>> import numpy as np
>>> signal = wd.read_wav("motor.wav")
>>> roughness_spec = signal.roughness_dw_spec(overlap=0.5)
>>>
>>> # Plot Bark-Time heatmap
>>> roughness_spec.plot(cmap="viridis", title="Roughness Analysis")
>>>
>>> # Find dominant Bark band
>>> dominant_idx = roughness_spec.data.mean(axis=1).argmax()
>>> dominant_bark = roughness_spec.bark_axis[dominant_idx]
>>> print(f"Most contributing band: {dominant_bark:.1f} Bark")
>>>
>>> # Extract specific Bark band time series
>>> bark_10_idx = np.argmin(np.abs(roughness_spec.bark_axis - 10.0))
>>> roughness_at_10bark = roughness_spec.data[bark_10_idx, :]
>>>
>>> # Verify standard formula
>>> total_roughness = 0.25 * roughness_spec.data.sum(axis=-2)
>>> # This should match signal.roughness_dw(overlap=0.5).data
Notes
- Returns a RoughnessFrame (not ChannelFrame)
- Contains 47 Bark bands from 0.5 to 23.5 Bark
- Each Bark band corresponds to a critical band of hearing
- Useful for identifying which frequencies contribute most to roughness
- The specific roughness can be integrated to obtain total roughness
- For simple time-series analysis, use roughness_dw() instead
Time axis convention: The time axis represents the start time of each 200ms analysis window, consistent with roughness_dw() and other wandas methods.
References
Daniel, P., & Weber, R. (1997). "Psychoacoustical roughness: Implementation of an optimized model." Acustica, 83, 113-123.
Source code in wandas/frames/mixins/channel_processing_mixin.py
695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 | |
fade(fade_ms=50)
¶Apply symmetric fade-in and fade-out to the signal using Tukey window.
This method applies a symmetric fade-in and fade-out envelope to the signal using a Tukey (tapered cosine) window. The fade duration is the same for both the beginning and end of the signal.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fade_ms
|
float
|
Fade duration in milliseconds for each end of the signal. The total fade duration is 2 * fade_ms. Default is 50 ms. Must be positive and less than half the signal duration. |
50
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame containing the faded signal |
Raises:
| Type | Description |
|---|---|
ValueError
|
If fade_ms is negative or too long for the signal |
Examples:
>>> import wandas as wd
>>> signal = wd.read_wav("audio.wav")
>>> # Apply 10ms fade-in and fade-out
>>> faded = signal.fade(fade_ms=10.0)
>>> # Apply very short fade (almost no effect)
>>> faded_short = signal.fade(fade_ms=0.1)
Notes
- Uses SciPy's Tukey window for smooth fade transitions
- Fade is applied symmetrically to both ends of the signal
- The Tukey window alpha parameter is computed automatically based on the fade duration and signal length
- For multi-channel signals, the same fade envelope is applied to all channels
- Lazy evaluation is preserved - computation occurs only when needed
Source code in wandas/frames/mixins/channel_processing_mixin.py
811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 | |
sharpness_din(weighting='din', field_type='free')
¶Calculate sharpness using DIN 45692 method.
This method computes the time-varying sharpness of the signal according to DIN 45692 standard, which quantifies the perceived sharpness of sounds.
Parameters¶
weighting : str, default="din" Weighting type for sharpness calculation. Options: - 'din': DIN 45692 method - 'aures': Aures method - 'bismarck': Bismarck method - 'fastl': Fastl method field_type : str, default="free" Type of sound field. Options: - 'free': Free field (sound from a specific direction) - 'diffuse': Diffuse field (sound from all directions)
Returns¶
T_Processing New ChannelFrame containing sharpness time series in acum. The output sampling rate is approximately 500 Hz (2ms time steps).
Raises¶
ValueError If the signal sampling rate is not supported by the algorithm.
Examples¶
import wandas as wd signal = wd.read_wav("sharp_sound.wav") sharpness = signal.sharpness_din(weighting="din", field_type="free") print(f"Mean sharpness: {sharpness.data.mean():.2f} acum")
Notes¶
- Sharpness is measured in acum (acum = 1 when the sound has the same sharpness as a 2 kHz narrow-band noise at 60 dB SPL)
- The calculation uses MoSQITo's implementation of DIN 45692
- Output sampling rate is fixed at 500 Hz regardless of input rate
- For multi-channel signals, sharpness is calculated per channel
References¶
.. [1] DIN 45692:2009, "Measurement technique for the simulation of the auditory sensation of sharpness"
Source code in wandas/frames/mixins/channel_processing_mixin.py
850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 | |
sharpness_din_st(weighting='din', field_type='free')
¶Calculate steady-state sharpness using DIN 45692 method.
This method computes the steady-state sharpness of the signal according to DIN 45692 standard, which quantifies the perceived sharpness of stationary sounds.
Parameters¶
weighting : str, default="din" Weighting type for sharpness calculation. Options: - 'din': DIN 45692 method - 'aures': Aures method - 'bismarck': Bismarck method - 'fastl': Fastl method field_type : str, default="free" Type of sound field. Options: - 'free': Free field (sound from a specific direction) - 'diffuse': Diffuse field (sound from all directions)
Returns¶
NDArrayReal Sharpness values in acum, one per channel. Shape: (n_channels,)
Raises¶
ValueError If the signal sampling rate is not supported by the algorithm.
Examples¶
import wandas as wd signal = wd.read_wav("constant_tone.wav") sharpness = signal.sharpness_din_st(weighting="din", field_type="free") print(f"Steady-state sharpness: {sharpness[0]:.2f} acum")
Notes¶
- Sharpness is measured in acum (acum = 1 when the sound has the same sharpness as a 2 kHz narrow-band noise at 60 dB SPL)
- The calculation uses MoSQITo's implementation of DIN 45692
- Output is a single value per channel, suitable for stationary signals
- For multi-channel signals, sharpness is calculated per channel
References¶
.. [1] DIN 45692:2009, "Measurement technique for the simulation of the auditory sensation of sharpness"
Source code in wandas/frames/mixins/channel_processing_mixin.py
918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 | |
ChannelTransformMixin
¶
Mixin providing methods related to frequency transformations.
This mixin provides operations related to frequency analysis and transformations such as FFT, STFT, and Welch method.
Source code in wandas/frames/mixins/channel_transform_mixin.py
19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 | |
fft(n_fft=None, window='hann')
¶Calculate Fast Fourier Transform (FFT).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_fft
|
int | None
|
Number of FFT points. Default is the next power of 2 of the data length. |
None
|
window
|
str
|
Window type. Default is "hann". |
'hann'
|
Returns:
| Type | Description |
|---|---|
SpectralFrame
|
SpectralFrame containing FFT results |
Source code in wandas/frames/mixins/channel_transform_mixin.py
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 | |
welch(n_fft=None, hop_length=None, win_length=2048, window='hann', average='mean')
¶Calculate power spectral density using Welch's method.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_fft
|
int | None
|
Number of FFT points. Default is 2048. |
None
|
hop_length
|
int | None
|
Number of samples between frames. Default is n_fft//4. |
None
|
win_length
|
int
|
Window length. Default is n_fft. |
2048
|
window
|
str
|
Window type. Default is "hann". |
'hann'
|
average
|
str
|
Method for averaging segments. Default is "mean". |
'mean'
|
Returns:
| Type | Description |
|---|---|
SpectralFrame
|
SpectralFrame containing power spectral density |
Source code in wandas/frames/mixins/channel_transform_mixin.py
84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 | |
noct_spectrum(fmin=25, fmax=20000, n=3, G=10, fr=1000)
¶Calculate N-octave band spectrum.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fmin
|
float
|
Minimum center frequency (Hz). Default is 25 Hz. |
25
|
fmax
|
float
|
Maximum center frequency (Hz). Default is 20000 Hz. |
20000
|
n
|
int
|
Band division (1: octave, 3: 1/3 octave). Default is 3. |
3
|
G
|
int
|
Reference gain (dB). Default is 10 dB. |
10
|
fr
|
int
|
Reference frequency (Hz). Default is 1000 Hz. |
1000
|
Returns:
| Type | Description |
|---|---|
NOctFrame
|
NOctFrame containing N-octave band spectrum |
Source code in wandas/frames/mixins/channel_transform_mixin.py
146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 | |
stft(n_fft=2048, hop_length=None, win_length=None, window='hann')
¶Calculate Short-Time Fourier Transform.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_fft
|
int
|
Number of FFT points. Default is 2048. |
2048
|
hop_length
|
int | None
|
Number of samples between frames. Default is n_fft//4. |
None
|
win_length
|
int | None
|
Window length. Default is n_fft. |
None
|
window
|
str
|
Window type. Default is "hann". |
'hann'
|
Returns:
| Type | Description |
|---|---|
SpectrogramFrame
|
SpectrogramFrame containing STFT results |
Source code in wandas/frames/mixins/channel_transform_mixin.py
208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 | |
coherence(n_fft=2048, hop_length=None, win_length=None, window='hann', detrend='constant')
¶Calculate magnitude squared coherence.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_fft
|
int
|
Number of FFT points. Default is 2048. |
2048
|
hop_length
|
int | None
|
Number of samples between frames. Default is n_fft//4. |
None
|
win_length
|
int | None
|
Window length. Default is n_fft. |
None
|
window
|
str
|
Window type. Default is "hann". |
'hann'
|
detrend
|
str
|
Detrend method. Options: "constant", "linear", None. |
'constant'
|
Returns:
| Type | Description |
|---|---|
SpectralFrame
|
SpectralFrame containing magnitude squared coherence |
Source code in wandas/frames/mixins/channel_transform_mixin.py
273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 | |
csd(n_fft=2048, hop_length=None, win_length=None, window='hann', detrend='constant', scaling='spectrum', average='mean')
¶Calculate cross-spectral density matrix.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_fft
|
int
|
Number of FFT points. Default is 2048. |
2048
|
hop_length
|
int | None
|
Number of samples between frames. Default is n_fft//4. |
None
|
win_length
|
int | None
|
Window length. Default is n_fft. |
None
|
window
|
str
|
Window type. Default is "hann". |
'hann'
|
detrend
|
str
|
Detrend method. Options: "constant", "linear", None. |
'constant'
|
scaling
|
str
|
Scaling method. Options: "spectrum", "density". |
'spectrum'
|
average
|
str
|
Method for averaging segments. Default is "mean". |
'mean'
|
Returns:
| Type | Description |
|---|---|
SpectralFrame
|
SpectralFrame containing cross-spectral density matrix |
Source code in wandas/frames/mixins/channel_transform_mixin.py
352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 | |
transfer_function(n_fft=2048, hop_length=None, win_length=None, window='hann', detrend='constant', scaling='spectrum', average='mean')
¶Calculate transfer function matrix.
The transfer function represents the signal transfer characteristics between channels in the frequency domain and represents the input-output relationship of the system.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_fft
|
int
|
Number of FFT points. Default is 2048. |
2048
|
hop_length
|
int | None
|
Number of samples between frames. Default is n_fft//4. |
None
|
win_length
|
int | None
|
Window length. Default is n_fft. |
None
|
window
|
str
|
Window type. Default is "hann". |
'hann'
|
detrend
|
str
|
Detrend method. Options: "constant", "linear", None. |
'constant'
|
scaling
|
str
|
Scaling method. Options: "spectrum", "density". |
'spectrum'
|
average
|
str
|
Method for averaging segments. Default is "mean". |
'mean'
|
Returns:
| Type | Description |
|---|---|
SpectralFrame
|
SpectralFrame containing transfer function matrix |
Source code in wandas/frames/mixins/channel_transform_mixin.py
436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 | |
Modules¶
channel_collection_mixin
¶
ChannelCollectionMixin: Common functionality for adding/removing channels in ChannelFrame
T = TypeVar('T', bound='ChannelCollectionMixin')
module-attribute
¶ ChannelCollectionMixin
¶Source code in wandas/frames/mixins/channel_collection_mixin.py
17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 | |
add_channel(data, label=None, align='strict', suffix_on_dup=None, inplace=False, **kwargs)
¶Add a channel Args: data: Channel to add (1ch ndarray/dask/ChannelFrame) label: Label for the added channel align: Behavior when lengths don't match suffix_on_dup: Suffix when label is duplicated inplace: True for self-modification Returns: New Frame or self Raises: ValueError, TypeError
Source code in wandas/frames/mixins/channel_collection_mixin.py
18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 | |
remove_channel(key, inplace=False)
¶Remove a channel Args: key: Target to remove (index or label) inplace: True for self-modification Returns: New Frame or self Raises: ValueError, KeyError, IndexError
Source code in wandas/frames/mixins/channel_collection_mixin.py
42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 | |
channel_processing_mixin
¶
Module providing mixins related to signal processing.
logger = logging.getLogger(__name__)
module-attribute
¶ ChannelProcessingMixin
¶Mixin that provides methods related to signal processing.
This mixin provides processing methods applied to audio signals and other time-series data, such as signal processing filters and transformation operations.
Source code in wandas/frames/mixins/channel_processing_mixin.py
25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 | |
high_pass_filter(cutoff, order=4)
¶Apply a high-pass filter to the signal.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cutoff
|
float
|
Filter cutoff frequency (Hz) |
required |
order
|
int
|
Filter order. Default is 4. |
4
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame after filter application |
Source code in wandas/frames/mixins/channel_processing_mixin.py
33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 | |
low_pass_filter(cutoff, order=4)
¶Apply a low-pass filter to the signal.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cutoff
|
float
|
Filter cutoff frequency (Hz) |
required |
order
|
int
|
Filter order. Default is 4. |
4
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame after filter application |
Source code in wandas/frames/mixins/channel_processing_mixin.py
51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 | |
band_pass_filter(low_cutoff, high_cutoff, order=4)
¶Apply a band-pass filter to the signal.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
low_cutoff
|
float
|
Lower cutoff frequency (Hz) |
required |
high_cutoff
|
float
|
Higher cutoff frequency (Hz) |
required |
order
|
int
|
Filter order. Default is 4. |
4
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame after filter application |
Source code in wandas/frames/mixins/channel_processing_mixin.py
69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 | |
normalize(norm=float('inf'), axis=-1, threshold=None, fill=None)
¶Normalize signal levels using librosa.util.normalize.
This method normalizes the signal amplitude according to the specified norm.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
norm
|
float | None
|
Norm type. Default is np.inf (maximum absolute value normalization). Supported values: - np.inf: Maximum absolute value normalization - -np.inf: Minimum absolute value normalization - 0: Peak normalization - float: Lp norm - None: No normalization |
float('inf')
|
axis
|
int | None
|
Axis along which to normalize. Default is -1 (time axis). - -1: Normalize along time axis (each channel independently) - None: Global normalization across all axes - int: Normalize along specified axis |
-1
|
threshold
|
float | None
|
Threshold below which values are considered zero. If None, no threshold is applied. |
None
|
fill
|
bool | None
|
Value to fill when the norm is zero. If None, the zero vector remains zero. |
None
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame containing the normalized signal |
Examples:
>>> import wandas as wd
>>> signal = wd.read_wav("audio.wav")
>>> # Normalize to maximum absolute value of 1.0 (per channel)
>>> normalized = signal.normalize()
>>> # Global normalization across all channels
>>> normalized_global = signal.normalize(axis=None)
>>> # L2 normalization
>>> normalized_l2 = signal.normalize(norm=2)
Source code in wandas/frames/mixins/channel_processing_mixin.py
94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 | |
remove_dc()
¶Remove DC component (DC offset) from the signal.
This method removes the DC (direct current) component by subtracting the mean value from each channel. This is equivalent to centering the signal around zero.
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame with DC component removed |
Examples:
>>> import wandas as wd
>>> import numpy as np
>>> # Create signal with DC offset
>>> signal = wd.read_wav("audio.wav")
>>> signal_with_dc = signal + 2.0 # Add DC offset
>>> # Remove DC offset
>>> signal_clean = signal_with_dc.remove_dc()
>>> # Verify DC removal
>>> assert np.allclose(signal_clean.data.mean(axis=1), 0, atol=1e-10)
Notes
- This operation is performed per channel
- Equivalent to applying a high-pass filter with very low cutoff
- Useful for removing sensor drift or measurement offset
Source code in wandas/frames/mixins/channel_processing_mixin.py
144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 | |
a_weighting()
¶Apply A-weighting filter to the signal.
A-weighting adjusts the frequency response to approximate human auditory perception, according to the IEC 61672-1:2013 standard.
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame containing the A-weighted signal |
Source code in wandas/frames/mixins/channel_processing_mixin.py
174 175 176 177 178 179 180 181 182 183 184 | |
abs()
¶Compute the absolute value of the signal.
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame containing the absolute values |
Source code in wandas/frames/mixins/channel_processing_mixin.py
186 187 188 189 190 191 192 193 | |
power(exponent=2.0)
¶Compute the power of the signal.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
exponent
|
float
|
Exponent to raise the signal to. Default is 2.0. |
2.0
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame containing the powered signal |
Source code in wandas/frames/mixins/channel_processing_mixin.py
195 196 197 198 199 200 201 202 203 204 205 | |
sum()
¶Sum all channels.
Returns:
| Type | Description |
|---|---|
T_Processing
|
A new ChannelFrame with summed signal. |
Source code in wandas/frames/mixins/channel_processing_mixin.py
245 246 247 248 249 250 251 | |
mean()
¶Average all channels.
Returns:
| Type | Description |
|---|---|
T_Processing
|
A new ChannelFrame with averaged signal. |
Source code in wandas/frames/mixins/channel_processing_mixin.py
253 254 255 256 257 258 259 | |
trim(start=0, end=None)
¶Trim the signal to the specified time range.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
start
|
float
|
Start time (seconds) |
0
|
end
|
float | None
|
End time (seconds) |
None
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame containing the trimmed signal |
Raises:
| Type | Description |
|---|---|
ValueError
|
If end time is earlier than start time |
Source code in wandas/frames/mixins/channel_processing_mixin.py
261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 | |
fix_length(length=None, duration=None)
¶Adjust the signal to the specified length.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
duration
|
float | None
|
Signal length in seconds |
None
|
length
|
int | None
|
Signal length in samples |
None
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame containing the adjusted signal |
Source code in wandas/frames/mixins/channel_processing_mixin.py
285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 | |
rms_trend(frame_length=2048, hop_length=512, dB=False, Aw=False)
¶Compute the RMS trend of the signal.
This method calculates the root mean square value over a sliding window.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
frame_length
|
int
|
Size of the sliding window in samples. Default is 2048. |
2048
|
hop_length
|
int
|
Hop length between windows in samples. Default is 512. |
512
|
dB
|
bool
|
Whether to return RMS values in decibels. Default is False. |
False
|
Aw
|
bool
|
Whether to apply A-weighting. Default is False. |
False
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame containing the RMS trend |
Source code in wandas/frames/mixins/channel_processing_mixin.py
303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 | |
channel_difference(other_channel=0)
¶Compute the difference between channels.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
other_channel
|
int | str
|
Index or label of the reference channel. Default is 0. |
0
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame containing the channel difference |
Source code in wandas/frames/mixins/channel_processing_mixin.py
343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 | |
resampling(target_sr, **kwargs)
¶Resample audio data.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target_sr
|
float
|
Target sampling rate (Hz) |
required |
**kwargs
|
Any
|
Additional resampling parameters |
{}
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
Resampled ChannelFrame |
Source code in wandas/frames/mixins/channel_processing_mixin.py
362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 | |
hpss_harmonic(kernel_size=31, power=2, margin=1, n_fft=2048, hop_length=None, win_length=None, window='hann', center=True, pad_mode='constant')
¶Extract harmonic components using HPSS (Harmonic-Percussive Source Separation).
This method separates the harmonic (tonal) components from the signal.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
kernel_size
|
Union[_IntLike_co, tuple[_IntLike_co, _IntLike_co], list[_IntLike_co]]
|
Median filter size for HPSS. |
31
|
power
|
float
|
Exponent for the Weiner filter used in HPSS. |
2
|
margin
|
Union[_FloatLike_co, tuple[_FloatLike_co, _FloatLike_co], list[_FloatLike_co]]
|
Margin size for the separation. |
1
|
n_fft
|
int
|
Size of FFT window. |
2048
|
hop_length
|
int | None
|
Hop length for STFT. |
None
|
win_length
|
int | None
|
Window length for STFT. |
None
|
window
|
_WindowSpec
|
Window type for STFT. |
'hann'
|
center
|
bool
|
If True, center the frames. |
True
|
pad_mode
|
_PadModeSTFT
|
Padding mode for STFT. |
'constant'
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
A new ChannelFrame containing the harmonic components. |
Source code in wandas/frames/mixins/channel_processing_mixin.py
385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 | |
hpss_percussive(kernel_size=31, power=2, margin=1, n_fft=2048, hop_length=None, win_length=None, window='hann', center=True, pad_mode='constant')
¶Extract percussive components using HPSS (Harmonic-Percussive Source Separation).
This method separates the percussive (tonal) components from the signal.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
kernel_size
|
Union[_IntLike_co, tuple[_IntLike_co, _IntLike_co], list[_IntLike_co]]
|
Median filter size for HPSS. |
31
|
power
|
float
|
Exponent for the Weiner filter used in HPSS. |
2
|
margin
|
Union[_FloatLike_co, tuple[_FloatLike_co, _FloatLike_co], list[_FloatLike_co]]
|
Margin size for the separation. |
1
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
A new ChannelFrame containing the harmonic components. |
Source code in wandas/frames/mixins/channel_processing_mixin.py
437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 | |
loudness_zwtv(field_type='free')
¶Calculate time-varying loudness using Zwicker method (ISO 532-1:2017).
This method computes the loudness of non-stationary signals according to the Zwicker method, as specified in ISO 532-1:2017. The loudness is calculated in sones, where a doubling of sones corresponds to a doubling of perceived loudness.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
field_type
|
str
|
Type of sound field. Options: - 'free': Free field (sound from a specific direction) - 'diffuse': Diffuse field (sound from all directions) Default is 'free'. |
'free'
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame containing time-varying loudness values in sones. |
T_Processing
|
Each channel is processed independently. |
T_Processing
|
The output sampling rate is adjusted based on the loudness |
T_Processing
|
calculation time resolution (typically ~500 Hz for 2ms steps). |
Raises:
| Type | Description |
|---|---|
ValueError
|
If field_type is not 'free' or 'diffuse' |
Examples:
Calculate loudness for a signal:
>>> import wandas as wd
>>> signal = wd.read_wav("audio.wav")
>>> loudness = signal.loudness_zwtv(field_type="free")
>>> loudness.plot(title="Time-varying Loudness")
Compare free field and diffuse field:
>>> loudness_free = signal.loudness_zwtv(field_type="free")
>>> loudness_diffuse = signal.loudness_zwtv(field_type="diffuse")
Notes
- The output contains time-varying loudness values in sones
- Typical loudness: 1 sone ≈ 40 phon (loudness level)
- The time resolution is approximately 2ms (determined by the algorithm)
- For multi-channel signals, loudness is calculated per channel
- The output sampling rate is updated to reflect the time resolution
Time axis convention: The time axis in the returned frame represents the start time of each 2ms analysis step. This differs slightly from the MoSQITo library, which uses the center time of each step. For example:
- wandas time: [0.000s, 0.002s, 0.004s, ...] (step start)
- MoSQITo time: [0.001s, 0.003s, 0.005s, ...] (step center)
The difference is very small (~1ms) and does not affect the loudness values themselves. This design choice ensures consistency with wandas's time axis convention across all frame types.
References
ISO 532-1:2017, "Acoustics — Methods for calculating loudness — Part 1: Zwicker method"
Source code in wandas/frames/mixins/channel_processing_mixin.py
483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 | |
loudness_zwst(field_type='free')
¶Calculate steady-state loudness using Zwicker method (ISO 532-1:2017).
This method computes the loudness of stationary (steady) signals according to the Zwicker method, as specified in ISO 532-1:2017. The loudness is calculated in sones, where a doubling of sones corresponds to a doubling of perceived loudness.
This method is suitable for analyzing steady sounds such as fan noise, constant machinery sounds, or other stationary signals.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
field_type
|
str
|
Type of sound field. Options: - 'free': Free field (sound from a specific direction) - 'diffuse': Diffuse field (sound from all directions) Default is 'free'. |
'free'
|
Returns:
| Type | Description |
|---|---|
NDArrayReal
|
Loudness values in sones, one per channel. Shape: (n_channels,) |
Raises:
| Type | Description |
|---|---|
ValueError
|
If field_type is not 'free' or 'diffuse' |
Examples:
Calculate steady-state loudness for a fan noise:
>>> import wandas as wd
>>> signal = wd.read_wav("fan_noise.wav")
>>> loudness = signal.loudness_zwst(field_type="free")
>>> print(f"Channel 0 loudness: {loudness[0]:.2f} sones")
>>> print(f"Mean loudness: {loudness.mean():.2f} sones")
Compare free field and diffuse field:
>>> loudness_free = signal.loudness_zwst(field_type="free")
>>> loudness_diffuse = signal.loudness_zwst(field_type="diffuse")
>>> print(f"Free field: {loudness_free[0]:.2f} sones")
>>> print(f"Diffuse field: {loudness_diffuse[0]:.2f} sones")
Notes
- Returns a 1D array with one loudness value per channel
- Typical loudness: 1 sone ≈ 40 phon (loudness level)
- For multi-channel signals, loudness is calculated independently per channel
- This method is designed for stationary signals (constant sounds)
- For time-varying signals, use loudness_zwtv() instead
- Similar to the rms property, returns NDArrayReal for consistency
References
ISO 532-1:2017, "Acoustics — Methods for calculating loudness — Part 1: Zwicker method"
Source code in wandas/frames/mixins/channel_processing_mixin.py
546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 | |
roughness_dw(overlap=0.5)
¶Calculate time-varying roughness using Daniel and Weber method.
Roughness is a psychoacoustic metric that quantifies the perceived harshness or roughness of a sound, measured in asper. This method implements the Daniel & Weber (1997) standard calculation.
The calculation follows the standard formula: R = 0.25 * sum(R'_i) for i=1 to 47 Bark bands
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
overlap
|
float
|
Overlapping coefficient for 200ms analysis windows (0.0 to 1.0). - overlap=0.5: 100ms hop → ~10 Hz output sampling rate - overlap=0.0: 200ms hop → ~5 Hz output sampling rate Default is 0.5. |
0.5
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame containing time-varying roughness values in asper. |
T_Processing
|
The output sampling rate depends on the overlap parameter. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If overlap is not in the range [0.0, 1.0] |
Examples:
Calculate roughness for a motor noise:
>>> import wandas as wd
>>> signal = wd.read_wav("motor_noise.wav")
>>> roughness = signal.roughness_dw(overlap=0.5)
>>> roughness.plot(ylabel="Roughness [asper]")
Analyze roughness statistics:
>>> mean_roughness = roughness.data.mean()
>>> max_roughness = roughness.data.max()
>>> print(f"Mean: {mean_roughness:.2f} asper")
>>> print(f"Max: {max_roughness:.2f} asper")
Compare before and after modification:
>>> before = wd.read_wav("motor_before.wav").roughness_dw()
>>> after = wd.read_wav("motor_after.wav").roughness_dw()
>>> improvement = before.data.mean() - after.data.mean()
>>> print(f"Roughness reduction: {improvement:.2f} asper")
Notes
- Returns a ChannelFrame with time-varying roughness values
- Typical roughness values: 0-2 asper for most sounds
- Higher values indicate rougher, harsher sounds
- For multi-channel signals, roughness is calculated independently per channel
- This is the standard-compliant total roughness (R)
- For detailed Bark-band analysis, use roughness_dw_spec() instead
Time axis convention: The time axis in the returned frame represents the start time of each 200ms analysis window. This differs from the MoSQITo library, which uses the center time of each window. For example:
- wandas time: [0.0s, 0.1s, 0.2s, ...] (window start)
- MoSQITo time: [0.1s, 0.2s, 0.3s, ...] (window center)
The difference is constant (half the window duration = 100ms) and does not affect the roughness values themselves. This design choice ensures consistency with wandas's time axis convention across all frame types.
References
Daniel, P., & Weber, R. (1997). "Psychoacoustical roughness: Implementation of an optimized model." Acustica, 83, 113-123.
Source code in wandas/frames/mixins/channel_processing_mixin.py
623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 | |
roughness_dw_spec(overlap=0.5)
¶Calculate specific roughness with Bark-band frequency information.
This method returns detailed roughness analysis data organized by Bark frequency bands over time, allowing for frequency-specific roughness analysis. It uses the Daniel & Weber (1997) method.
The relationship between total roughness and specific roughness: R = 0.25 * sum(R'_i) for i=1 to 47 Bark bands
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
overlap
|
float
|
Overlapping coefficient for 200ms analysis windows (0.0 to 1.0). - overlap=0.5: 100ms hop → ~10 Hz output sampling rate - overlap=0.0: 200ms hop → ~5 Hz output sampling rate Default is 0.5. |
0.5
|
Returns:
| Type | Description |
|---|---|
RoughnessFrame
|
RoughnessFrame containing: - data: Specific roughness by Bark band, shape (47, n_time) for mono or (n_channels, 47, n_time) for multi-channel - bark_axis: Frequency axis in Bark scale (47 values, 0.5-23.5) - time: Time axis for each analysis frame - overlap: Overlap coefficient used - plot(): Method for Bark-Time heatmap visualization |
Raises:
| Type | Description |
|---|---|
ValueError
|
If overlap is not in the range [0.0, 1.0] |
Examples:
Analyze frequency-specific roughness:
>>> import wandas as wd
>>> import numpy as np
>>> signal = wd.read_wav("motor.wav")
>>> roughness_spec = signal.roughness_dw_spec(overlap=0.5)
>>>
>>> # Plot Bark-Time heatmap
>>> roughness_spec.plot(cmap="viridis", title="Roughness Analysis")
>>>
>>> # Find dominant Bark band
>>> dominant_idx = roughness_spec.data.mean(axis=1).argmax()
>>> dominant_bark = roughness_spec.bark_axis[dominant_idx]
>>> print(f"Most contributing band: {dominant_bark:.1f} Bark")
>>>
>>> # Extract specific Bark band time series
>>> bark_10_idx = np.argmin(np.abs(roughness_spec.bark_axis - 10.0))
>>> roughness_at_10bark = roughness_spec.data[bark_10_idx, :]
>>>
>>> # Verify standard formula
>>> total_roughness = 0.25 * roughness_spec.data.sum(axis=-2)
>>> # This should match signal.roughness_dw(overlap=0.5).data
Notes
- Returns a RoughnessFrame (not ChannelFrame)
- Contains 47 Bark bands from 0.5 to 23.5 Bark
- Each Bark band corresponds to a critical band of hearing
- Useful for identifying which frequencies contribute most to roughness
- The specific roughness can be integrated to obtain total roughness
- For simple time-series analysis, use roughness_dw() instead
Time axis convention: The time axis represents the start time of each 200ms analysis window, consistent with roughness_dw() and other wandas methods.
References
Daniel, P., & Weber, R. (1997). "Psychoacoustical roughness: Implementation of an optimized model." Acustica, 83, 113-123.
Source code in wandas/frames/mixins/channel_processing_mixin.py
695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 | |
fade(fade_ms=50)
¶Apply symmetric fade-in and fade-out to the signal using Tukey window.
This method applies a symmetric fade-in and fade-out envelope to the signal using a Tukey (tapered cosine) window. The fade duration is the same for both the beginning and end of the signal.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fade_ms
|
float
|
Fade duration in milliseconds for each end of the signal. The total fade duration is 2 * fade_ms. Default is 50 ms. Must be positive and less than half the signal duration. |
50
|
Returns:
| Type | Description |
|---|---|
T_Processing
|
New ChannelFrame containing the faded signal |
Raises:
| Type | Description |
|---|---|
ValueError
|
If fade_ms is negative or too long for the signal |
Examples:
>>> import wandas as wd
>>> signal = wd.read_wav("audio.wav")
>>> # Apply 10ms fade-in and fade-out
>>> faded = signal.fade(fade_ms=10.0)
>>> # Apply very short fade (almost no effect)
>>> faded_short = signal.fade(fade_ms=0.1)
Notes
- Uses SciPy's Tukey window for smooth fade transitions
- Fade is applied symmetrically to both ends of the signal
- The Tukey window alpha parameter is computed automatically based on the fade duration and signal length
- For multi-channel signals, the same fade envelope is applied to all channels
- Lazy evaluation is preserved - computation occurs only when needed
Source code in wandas/frames/mixins/channel_processing_mixin.py
811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 | |
sharpness_din(weighting='din', field_type='free')
¶Calculate sharpness using DIN 45692 method.
This method computes the time-varying sharpness of the signal according to DIN 45692 standard, which quantifies the perceived sharpness of sounds.
Parameters¶
weighting : str, default="din" Weighting type for sharpness calculation. Options: - 'din': DIN 45692 method - 'aures': Aures method - 'bismarck': Bismarck method - 'fastl': Fastl method field_type : str, default="free" Type of sound field. Options: - 'free': Free field (sound from a specific direction) - 'diffuse': Diffuse field (sound from all directions)
Returns¶
T_Processing New ChannelFrame containing sharpness time series in acum. The output sampling rate is approximately 500 Hz (2ms time steps).
Raises¶
ValueError If the signal sampling rate is not supported by the algorithm.
Examples¶
import wandas as wd signal = wd.read_wav("sharp_sound.wav") sharpness = signal.sharpness_din(weighting="din", field_type="free") print(f"Mean sharpness: {sharpness.data.mean():.2f} acum")
Notes¶
- Sharpness is measured in acum (acum = 1 when the sound has the same sharpness as a 2 kHz narrow-band noise at 60 dB SPL)
- The calculation uses MoSQITo's implementation of DIN 45692
- Output sampling rate is fixed at 500 Hz regardless of input rate
- For multi-channel signals, sharpness is calculated per channel
References¶
.. [1] DIN 45692:2009, "Measurement technique for the simulation of the auditory sensation of sharpness"
Source code in wandas/frames/mixins/channel_processing_mixin.py
850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 | |
sharpness_din_st(weighting='din', field_type='free')
¶Calculate steady-state sharpness using DIN 45692 method.
This method computes the steady-state sharpness of the signal according to DIN 45692 standard, which quantifies the perceived sharpness of stationary sounds.
Parameters¶
weighting : str, default="din" Weighting type for sharpness calculation. Options: - 'din': DIN 45692 method - 'aures': Aures method - 'bismarck': Bismarck method - 'fastl': Fastl method field_type : str, default="free" Type of sound field. Options: - 'free': Free field (sound from a specific direction) - 'diffuse': Diffuse field (sound from all directions)
Returns¶
NDArrayReal Sharpness values in acum, one per channel. Shape: (n_channels,)
Raises¶
ValueError If the signal sampling rate is not supported by the algorithm.
Examples¶
import wandas as wd signal = wd.read_wav("constant_tone.wav") sharpness = signal.sharpness_din_st(weighting="din", field_type="free") print(f"Steady-state sharpness: {sharpness[0]:.2f} acum")
Notes¶
- Sharpness is measured in acum (acum = 1 when the sound has the same sharpness as a 2 kHz narrow-band noise at 60 dB SPL)
- The calculation uses MoSQITo's implementation of DIN 45692
- Output is a single value per channel, suitable for stationary signals
- For multi-channel signals, sharpness is calculated per channel
References¶
.. [1] DIN 45692:2009, "Measurement technique for the simulation of the auditory sensation of sharpness"
Source code in wandas/frames/mixins/channel_processing_mixin.py
918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 | |
channel_transform_mixin
¶
Module providing mixins related to frequency transformations and transform operations.
logger = logging.getLogger(__name__)
module-attribute
¶ ChannelTransformMixin
¶Mixin providing methods related to frequency transformations.
This mixin provides operations related to frequency analysis and transformations such as FFT, STFT, and Welch method.
Source code in wandas/frames/mixins/channel_transform_mixin.py
19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 | |
fft(n_fft=None, window='hann')
¶Calculate Fast Fourier Transform (FFT).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_fft
|
int | None
|
Number of FFT points. Default is the next power of 2 of the data length. |
None
|
window
|
str
|
Window type. Default is "hann". |
'hann'
|
Returns:
| Type | Description |
|---|---|
SpectralFrame
|
SpectralFrame containing FFT results |
Source code in wandas/frames/mixins/channel_transform_mixin.py
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 | |
welch(n_fft=None, hop_length=None, win_length=2048, window='hann', average='mean')
¶Calculate power spectral density using Welch's method.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_fft
|
int | None
|
Number of FFT points. Default is 2048. |
None
|
hop_length
|
int | None
|
Number of samples between frames. Default is n_fft//4. |
None
|
win_length
|
int
|
Window length. Default is n_fft. |
2048
|
window
|
str
|
Window type. Default is "hann". |
'hann'
|
average
|
str
|
Method for averaging segments. Default is "mean". |
'mean'
|
Returns:
| Type | Description |
|---|---|
SpectralFrame
|
SpectralFrame containing power spectral density |
Source code in wandas/frames/mixins/channel_transform_mixin.py
84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 | |
noct_spectrum(fmin=25, fmax=20000, n=3, G=10, fr=1000)
¶Calculate N-octave band spectrum.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fmin
|
float
|
Minimum center frequency (Hz). Default is 25 Hz. |
25
|
fmax
|
float
|
Maximum center frequency (Hz). Default is 20000 Hz. |
20000
|
n
|
int
|
Band division (1: octave, 3: 1/3 octave). Default is 3. |
3
|
G
|
int
|
Reference gain (dB). Default is 10 dB. |
10
|
fr
|
int
|
Reference frequency (Hz). Default is 1000 Hz. |
1000
|
Returns:
| Type | Description |
|---|---|
NOctFrame
|
NOctFrame containing N-octave band spectrum |
Source code in wandas/frames/mixins/channel_transform_mixin.py
146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 | |
stft(n_fft=2048, hop_length=None, win_length=None, window='hann')
¶Calculate Short-Time Fourier Transform.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_fft
|
int
|
Number of FFT points. Default is 2048. |
2048
|
hop_length
|
int | None
|
Number of samples between frames. Default is n_fft//4. |
None
|
win_length
|
int | None
|
Window length. Default is n_fft. |
None
|
window
|
str
|
Window type. Default is "hann". |
'hann'
|
Returns:
| Type | Description |
|---|---|
SpectrogramFrame
|
SpectrogramFrame containing STFT results |
Source code in wandas/frames/mixins/channel_transform_mixin.py
208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 | |
coherence(n_fft=2048, hop_length=None, win_length=None, window='hann', detrend='constant')
¶Calculate magnitude squared coherence.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_fft
|
int
|
Number of FFT points. Default is 2048. |
2048
|
hop_length
|
int | None
|
Number of samples between frames. Default is n_fft//4. |
None
|
win_length
|
int | None
|
Window length. Default is n_fft. |
None
|
window
|
str
|
Window type. Default is "hann". |
'hann'
|
detrend
|
str
|
Detrend method. Options: "constant", "linear", None. |
'constant'
|
Returns:
| Type | Description |
|---|---|
SpectralFrame
|
SpectralFrame containing magnitude squared coherence |
Source code in wandas/frames/mixins/channel_transform_mixin.py
273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 | |
csd(n_fft=2048, hop_length=None, win_length=None, window='hann', detrend='constant', scaling='spectrum', average='mean')
¶Calculate cross-spectral density matrix.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_fft
|
int
|
Number of FFT points. Default is 2048. |
2048
|
hop_length
|
int | None
|
Number of samples between frames. Default is n_fft//4. |
None
|
win_length
|
int | None
|
Window length. Default is n_fft. |
None
|
window
|
str
|
Window type. Default is "hann". |
'hann'
|
detrend
|
str
|
Detrend method. Options: "constant", "linear", None. |
'constant'
|
scaling
|
str
|
Scaling method. Options: "spectrum", "density". |
'spectrum'
|
average
|
str
|
Method for averaging segments. Default is "mean". |
'mean'
|
Returns:
| Type | Description |
|---|---|
SpectralFrame
|
SpectralFrame containing cross-spectral density matrix |
Source code in wandas/frames/mixins/channel_transform_mixin.py
352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 | |
transfer_function(n_fft=2048, hop_length=None, win_length=None, window='hann', detrend='constant', scaling='spectrum', average='mean')
¶Calculate transfer function matrix.
The transfer function represents the signal transfer characteristics between channels in the frequency domain and represents the input-output relationship of the system.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_fft
|
int
|
Number of FFT points. Default is 2048. |
2048
|
hop_length
|
int | None
|
Number of samples between frames. Default is n_fft//4. |
None
|
win_length
|
int | None
|
Window length. Default is n_fft. |
None
|
window
|
str
|
Window type. Default is "hann". |
'hann'
|
detrend
|
str
|
Detrend method. Options: "constant", "linear", None. |
'constant'
|
scaling
|
str
|
Scaling method. Options: "spectrum", "density". |
'spectrum'
|
average
|
str
|
Method for averaging segments. Default is "mean". |
'mean'
|
Returns:
| Type | Description |
|---|---|
SpectralFrame
|
SpectralFrame containing transfer function matrix |
Source code in wandas/frames/mixins/channel_transform_mixin.py
436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 | |
protocols
¶
Common protocol definition module.
This module contains common protocols used by mixin classes.
logger = logging.getLogger(__name__)
module-attribute
¶ T_Base = TypeVar('T_Base', bound='BaseFrameProtocol')
module-attribute
¶ T_Processing = TypeVar('T_Processing', bound=ProcessingFrameProtocol)
module-attribute
¶ T_Transform = TypeVar('T_Transform', bound=TransformFrameProtocol)
module-attribute
¶ __all__ = ['BaseFrameProtocol', 'ProcessingFrameProtocol', 'TransformFrameProtocol', 'T_Processing']
module-attribute
¶ BaseFrameProtocol
¶
Bases: Protocol
Protocol that defines basic frame operations.
Defines the basic methods and properties provided by all frame classes.
Source code in wandas/frames/mixins/protocols.py
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 | |
sampling_rate
instance-attribute
¶ metadata
instance-attribute
¶ operation_history
instance-attribute
¶ label
instance-attribute
¶ duration
property
¶Returns the duration in seconds.
data
property
¶Returns the computed data as a NumPy array.
Implementations should materialize any lazy computation (e.g. Dask) and return a concrete NumPy array.
label2index(label)
¶Get the index from a channel label.
Source code in wandas/frames/mixins/protocols.py
48 49 50 51 52 | |
apply_operation(operation_name, **params)
¶Apply a named operation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
operation_name
|
str
|
Name of the operation to apply |
required |
**params
|
Any
|
Parameters to pass to the operation |
{}
|
Returns:
| Type | Description |
|---|---|
BaseFrameProtocol
|
A new frame instance with the operation applied |
Source code in wandas/frames/mixins/protocols.py
54 55 56 57 58 59 60 61 62 63 64 65 66 | |
ProcessingFrameProtocol
¶
Bases: BaseFrameProtocol, Protocol
Protocol that defines operations related to signal processing.
Defines methods that provide frame operations related to signal processing.
Source code in wandas/frames/mixins/protocols.py
81 82 83 84 85 86 87 88 | |
TransformFrameProtocol
¶
Bases: BaseFrameProtocol, Protocol
Protocol related to transform operations.
Defines methods that provide operations such as frequency analysis and spectral transformation.
Source code in wandas/frames/mixins/protocols.py
91 92 93 94 95 96 97 98 99 | |
noct
¶
Attributes¶
dask_delayed = dask.delayed
module-attribute
¶
da_from_delayed = da.from_delayed
module-attribute
¶
logger = logging.getLogger(__name__)
module-attribute
¶
S = TypeVar('S', bound='BaseFrame[Any]')
module-attribute
¶
Classes¶
NOctFrame
¶
Bases: BaseFrame[NDArrayReal]
Class for handling N-octave band analysis data.
This class represents frequency data analyzed in fractional octave bands, typically used in acoustic and vibration analysis. It handles real-valued data representing energy or power in each frequency band, following standard acoustical band definitions.
Parameters¶
data : DaArray The N-octave band data. Must be a dask array with shape: - (channels, frequency_bins) for multi-channel data - (frequency_bins,) for single-channel data, which will be reshaped to (1, frequency_bins) sampling_rate : float The sampling rate of the original time-domain signal in Hz. fmin : float, default=0 Lower frequency bound in Hz. fmax : float, default=0 Upper frequency bound in Hz. n : int, default=3 Number of bands per octave (e.g., 3 for third-octave bands). G : int, default=10 Reference band number according to IEC 61260-1:2014. fr : int, default=1000 Reference frequency in Hz, typically 1000 Hz for acoustic analysis. label : str, optional A label for the frame. metadata : dict, optional Additional metadata for the frame. operation_history : list[dict], optional History of operations performed on this frame. channel_metadata : list[ChannelMetadata], optional Metadata for each channel in the frame. previous : BaseFrame, optional The frame that this frame was derived from.
Attributes¶
freqs : NDArrayReal The center frequencies of each band in Hz, calculated according to the standard fractional octave band definitions. dB : NDArrayReal The spectrum in decibels relative to channel reference values. dBA : NDArrayReal The A-weighted spectrum in decibels, applying frequency weighting for better correlation with perceived loudness. fmin : float Lower frequency bound in Hz. fmax : float Upper frequency bound in Hz. n : int Number of bands per octave. G : int Reference band number. fr : int Reference frequency in Hz.
Examples¶
Create an N-octave band spectrum from a time-domain signal:
signal = ChannelFrame.from_wav("audio.wav") spectrum = signal.noct_spectrum(fmin=20, fmax=20000, n=3)
Plot the N-octave band spectrum:
spectrum.plot()
Plot with A-weighting applied:
spectrum.plot(Aw=True)
Notes¶
- Binary operations (addition, multiplication, etc.) are not currently supported for N-octave band data.
- The actual frequency bands are determined by the parameters n, G, and fr according to IEC 61260-1:2014 standard for fractional octave band filters.
- The class follows acoustic standards for band definitions and analysis, making it suitable for noise measurements and sound level analysis.
- A-weighting is available for better correlation with human hearing perception, following IEC 61672-1:2013.
Source code in wandas/frames/noct.py
32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 | |
n = n
instance-attribute
¶ G = G
instance-attribute
¶ fr = fr
instance-attribute
¶ fmin = fmin
instance-attribute
¶ fmax = fmax
instance-attribute
¶ dB
property
¶Get the spectrum in decibels relative to each channel's reference value.
The reference value for each channel is specified in its metadata. A minimum value of -120 dB is enforced to avoid numerical issues.
Returns¶
NDArrayReal The spectrum in decibels. Shape matches the input data shape: (channels, frequency_bins).
dBA
property
¶Get the A-weighted spectrum in decibels.
A-weighting applies a frequency-dependent weighting filter that approximates the human ear's response to different frequencies. This is particularly useful for analyzing noise and acoustic measurements as it provides a better correlation with perceived loudness.
The weighting is applied according to IEC 61672-1:2013 standard.
Returns¶
NDArrayReal The A-weighted spectrum in decibels. Shape matches the input data shape: (channels, frequency_bins).
freqs
property
¶Get the center frequencies of each band in Hz.
These frequencies are calculated based on the N-octave band parameters (n, G, fr) and the frequency bounds (fmin, fmax) according to IEC 61260-1:2014 standard for fractional octave band filters.
Returns¶
NDArrayReal Array of center frequencies for each frequency band.
Raises¶
ValueError If the center frequencies cannot be calculated or the result is not a numpy array.
__init__(data, sampling_rate, fmin=0, fmax=0, n=3, G=10, fr=1000, label=None, metadata=None, operation_history=None, channel_metadata=None, previous=None)
¶Initialize a NOctFrame instance.
Sets up N-octave band analysis parameters and prepares the frame for storing band-filtered data. Data shape is validated to ensure compatibility with N-octave band analysis.
See class docstring for parameter descriptions.
Source code in wandas/frames/noct.py
122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 | |
plot(plot_type='noct', ax=None, title=None, overlay=False, xlabel=None, ylabel=None, alpha=1.0, xlim=None, ylim=None, Aw=False, **kwargs)
¶Plot the N-octave band data using various visualization strategies.
Supports standard plotting configurations for acoustic analysis, including decibel scales and A-weighting.
Parameters¶
plot_type : str, default="noct" Type of plot to create. The default "noct" type creates a step plot suitable for displaying N-octave band data. ax : matplotlib.axes.Axes, optional Axes to plot on. If None, creates new axes. title : str, optional Title for the plot. If None, uses a default title with band specification. overlay : bool, default=False Whether to overlay all channels on a single plot (True) or create separate subplots for each channel (False). xlabel : str, optional Label for the x-axis. If None, uses default "Center frequency [Hz]". ylabel : str, optional Label for the y-axis. If None, uses default based on data type. alpha : float, default=1.0 Transparency level for the plot lines (0.0 to 1.0). xlim : tuple[float, float], optional Limits for the x-axis as (min, max) tuple. ylim : tuple[float, float], optional Limits for the y-axis as (min, max) tuple. Aw : bool, default=False Whether to apply A-weighting to the data. **kwargs : dict Additional matplotlib Line2D parameters (e.g., color, linewidth, linestyle).
Returns¶
Union[Axes, Iterator[Axes]] The matplotlib axes containing the plot, or an iterator of axes for multi-plot outputs.
Examples¶
noct = spectrum.noct(n=3)
Basic 1/3-octave plot¶
noct.plot()
Overlay with A-weighting¶
noct.plot(overlay=True, Aw=True)
Custom styling¶
noct.plot(title="1/3-Octave Spectrum", color="blue", linewidth=2)
Source code in wandas/frames/noct.py
289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 | |
roughness
¶
Roughness analysis frame for detailed psychoacoustic analysis.
Attributes¶
logger = logging.getLogger(__name__)
module-attribute
¶
Classes¶
RoughnessFrame
¶
Bases: BaseFrame[NDArrayReal]
Frame for detailed roughness analysis with Bark-band information.
This frame contains specific roughness (R_spec) data organized by Bark frequency bands over time, calculated using the Daniel & Weber (1997) method.
The relationship between total roughness and specific roughness follows: R = 0.25 * sum(R_spec, axis=bark_bands)
Parameters¶
data : da.Array Specific roughness data with shape: - (n_bark_bands, n_time) for mono signals - (n_channels, n_bark_bands, n_time) for multi-channel signals where n_bark_bands is always 47. sampling_rate : float Sampling rate of the roughness time series in Hz. For overlap=0.5, this is approximately 10 Hz (100ms hop). For overlap=0.0, this is approximately 5 Hz (200ms hop). bark_axis : NDArrayReal Bark frequency axis with 47 values from 0.5 to 23.5 Bark. overlap : float Overlap coefficient used in the calculation (0.0 to 1.0). label : str, optional Frame label. Defaults to "roughness_spec". metadata : dict, optional Additional metadata. operation_history : list[dict], optional History of operations applied to this frame. channel_metadata : list[ChannelMetadata], optional Metadata for each channel. previous : BaseFrame, optional Reference to the previous frame in the processing chain.
Attributes¶
bark_axis : NDArrayReal Frequency axis in Bark scale. n_bark_bands : int Number of Bark bands (always 47). n_time_points : int Number of time points. time : NDArrayReal Time axis based on sampling rate. overlap : float Overlap coefficient used (0.0 to 1.0).
Examples¶
Create a roughness frame from a signal:
import wandas as wd signal = wd.read_wav("motor.wav") roughness_spec = signal.roughness_dw_spec(overlap=0.5)
Plot Bark-Time heatmap¶
roughness_spec.plot()
Find dominant Bark band¶
dominant_idx = roughness_spec.data.mean(axis=1).argmax() dominant_bark = roughness_spec.bark_axis[dominant_idx] print(f"Dominant frequency: {dominant_bark:.1f} Bark")
Extract specific Bark band¶
bark_10_idx = np.argmin(np.abs(roughness_spec.bark_axis - 10.0)) roughness_at_10bark = roughness_spec.data[bark_10_idx, :]
Notes¶
The Daniel & Weber (1997) roughness model calculates specific roughness for 47 critical bands (Bark scale) over time, then integrates them to produce the total roughness:
.. math:: R = 0.25 \sum_{i=1}^{47} R'_i
where R'_i is the specific roughness in the i-th Bark band.
References¶
.. [1] Daniel, P., & Weber, R. (1997). "Psychoacoustical roughness: Implementation of an optimized model". Acta Acustica united with Acustica, 83(1), 113-123.
Source code in wandas/frames/roughness.py
22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 | |
data
property
¶Returns the computed data without squeezing.
For RoughnessFrame, even mono signals have 2D shape (47, n_time) so we don't squeeze the channel dimension.
Returns¶
NDArrayReal Computed data array.
bark_axis
property
¶ n_time_points
property
¶Number of time points in the roughness time series.
Returns¶
int Number of time frames in the analysis.
time
property
¶ overlap
property
¶ __init__(data, sampling_rate, bark_axis, overlap, label=None, metadata=None, operation_history=None, channel_metadata=None, previous=None)
¶Initialize a RoughnessFrame.
Source code in wandas/frames/roughness.py
110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 | |
to_dataframe()
¶DataFrame conversion is not supported for RoughnessFrame.
RoughnessFrame contains 3D data (channels, bark_bands, time_frames) which cannot be directly converted to a 2D DataFrame.
Raises¶
NotImplementedError Always raised as DataFrame conversion is not supported.
Source code in wandas/frames/roughness.py
274 275 276 277 278 279 280 281 282 283 284 285 286 287 | |
plot(plot_type='heatmap', ax=None, title=None, cmap='viridis', vmin=None, vmax=None, xlabel='Time [s]', ylabel='Frequency [Bark]', colorbar_label='Specific Roughness [Asper/Bark]', **kwargs)
¶Plot Bark-Time-Roughness heatmap.
For multi-channel signals, the mean across channels is plotted.
Parameters¶
ax : Axes, optional Matplotlib axes to plot on. If None, a new figure is created. title : str, optional Plot title. If None, a default title is used. cmap : str, default="viridis" Colormap name for the heatmap. vmin, vmax : float, optional Color scale limits. If None, automatic scaling is used. xlabel : str, default="Time [s]" Label for the x-axis. ylabel : str, default="Frequency [Bark]" Label for the y-axis. colorbar_label : str, default="Specific Roughness [Asper/Bark]" Label for the colorbar. **kwargs : Any Additional keyword arguments passed to pcolormesh.
Returns¶
Axes The matplotlib axes object containing the plot.
Examples¶
import wandas as wd signal = wd.read_wav("motor.wav") roughness_spec = signal.roughness_dw_spec(overlap=0.5) roughness_spec.plot(cmap="hot", title="Motor Roughness Analysis")
Source code in wandas/frames/roughness.py
401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 | |
spectral
¶
Attributes¶
dask_delayed = dask.delayed
module-attribute
¶
da_from_delayed = da.from_delayed
module-attribute
¶
logger = logging.getLogger(__name__)
module-attribute
¶
S = TypeVar('S', bound='BaseFrame[Any]')
module-attribute
¶
Classes¶
SpectralFrame
¶
Bases: BaseFrame[NDArrayComplex]
Class for handling frequency-domain signal data.
This class represents spectral data, providing methods for spectral analysis, manipulation, and visualization. It handles complex-valued frequency domain data obtained through operations like FFT.
Parameters¶
data : DaArray The spectral data. Must be a dask array with shape: - (channels, frequency_bins) for multi-channel data - (frequency_bins,) for single-channel data, which will be reshaped to (1, frequency_bins) sampling_rate : float The sampling rate of the original time-domain signal in Hz. n_fft : int The FFT size used to generate this spectral data. window : str, default="hann" The window function used in the FFT. label : str, optional A label for the frame. metadata : dict, optional Additional metadata for the frame. operation_history : list[dict], optional History of operations performed on this frame. channel_metadata : list[ChannelMetadata], optional Metadata for each channel in the frame. previous : BaseFrame, optional The frame that this frame was derived from.
Attributes¶
magnitude : NDArrayReal The magnitude spectrum of the data. phase : NDArrayReal The phase spectrum in radians. unwrapped_phase : NDArrayReal The unwrapped phase spectrum in radians. power : NDArrayReal The power spectrum (magnitude squared). dB : NDArrayReal The spectrum in decibels relative to channel reference values. dBA : NDArrayReal The A-weighted spectrum in decibels. freqs : NDArrayReal The frequency axis values in Hz.
Examples¶
Create a SpectralFrame from FFT:
signal = ChannelFrame.from_numpy(data, sampling_rate=44100) spectrum = signal.fft(n_fft=2048)
Plot the magnitude spectrum:
spectrum.plot()
Perform binary operations:
scaled = spectrum * 2.0 summed = spectrum1 + spectrum2 # Must have matching sampling rates
Convert back to time domain:
time_signal = spectrum.ifft()
Notes¶
- All operations are performed lazily using dask arrays for efficient memory usage.
- Binary operations (+, -, *, /) can be performed between SpectralFrames or with scalar values.
- The class maintains the processing history and metadata through all operations.
Source code in wandas/frames/spectral.py
36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 | |
n_fft = n_fft
instance-attribute
¶ window = window
instance-attribute
¶ magnitude
property
¶ phase
property
¶ unwrapped_phase
property
¶Get the unwrapped phase spectrum.
The unwrapped phase removes discontinuities of 2π radians, providing continuous phase values across frequency bins.
Returns¶
NDArrayReal The unwrapped phase angles of the complex spectrum in radians.
dB
property
¶Get the spectrum in decibels.
The reference values are taken from channel metadata. If no reference is specified, uses 1.0.
Returns¶
NDArrayReal The spectrum in dB relative to channel references.
dBA
property
¶Get the A-weighted spectrum in decibels.
Applies A-weighting filter to the spectrum for better correlation with perceived loudness.
Returns¶
NDArrayReal The A-weighted spectrum in dB.
freqs
property
¶Get the frequency axis values in Hz.
Returns¶
NDArrayReal Array of frequency values corresponding to each frequency bin.
__init__(data, sampling_rate, n_fft, window='hann', label=None, metadata=None, operation_history=None, channel_metadata=None, previous=None)
¶Source code in wandas/frames/spectral.py
112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 | |
plot(plot_type='frequency', ax=None, title=None, overlay=False, xlabel=None, ylabel=None, alpha=1.0, xlim=None, ylim=None, Aw=False, **kwargs)
¶Plot the spectral data using various visualization strategies.
Parameters¶
plot_type : str, default="frequency" Type of plot to create. Options include: - "frequency": Standard frequency plot - "matrix": Matrix plot for comparing channels - Other types as defined by available plot strategies ax : matplotlib.axes.Axes, optional Axes to plot on. If None, creates new axes. title : str, optional Title for the plot. If None, uses the frame label. overlay : bool, default=False Whether to overlay all channels on a single plot (True) or create separate subplots for each channel (False). xlabel : str, optional Label for the x-axis. If None, uses default "Frequency [Hz]". ylabel : str, optional Label for the y-axis. If None, uses default based on data type. alpha : float, default=1.0 Transparency level for the plot lines (0.0 to 1.0). xlim : tuple[float, float], optional Limits for the x-axis as (min, max) tuple. ylim : tuple[float, float], optional Limits for the y-axis as (min, max) tuple. Aw : bool, default=False Whether to apply A-weighting to the data. **kwargs : dict Additional matplotlib Line2D parameters (e.g., color, linewidth, linestyle).
Returns¶
Union[Axes, Iterator[Axes]] The matplotlib axes containing the plot, or an iterator of axes for multi-plot outputs.
Examples¶
spectrum = cf.fft()
Basic frequency plot¶
spectrum.plot()
Overlay with A-weighting¶
spectrum.plot(overlay=True, Aw=True)
Custom styling¶
spectrum.plot(title="Frequency Spectrum", color="red", linewidth=2)
Source code in wandas/frames/spectral.py
420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 | |
ifft()
¶Compute the Inverse Fast Fourier Transform (IFFT) to return to time domain.
This method transforms the frequency-domain data back to the time domain using the inverse FFT operation. The window function used in the forward FFT is taken into account to ensure proper reconstruction.
Returns¶
ChannelFrame A new ChannelFrame containing the time-domain signal.
Source code in wandas/frames/spectral.py
515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 | |
noct_synthesis(fmin, fmax, n=3, G=10, fr=1000)
¶Synthesize N-octave band spectrum.
This method combines frequency components into N-octave bands according to standard acoustical band definitions. This is commonly used in noise and vibration analysis.
Parameters¶
fmin : float Lower frequency bound in Hz. fmax : float Upper frequency bound in Hz. n : int, default=3 Number of bands per octave (e.g., 3 for third-octave bands). G : int, default=10 Reference band number. fr : int, default=1000 Reference frequency in Hz.
Returns¶
NOctFrame A new NOctFrame containing the N-octave band spectrum.
Raises¶
ValueError If the sampling rate is not 48000 Hz, which is required for this operation.
Source code in wandas/frames/spectral.py
577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 | |
plot_matrix(plot_type='matrix', **kwargs)
¶Plot channel relationships in matrix format.
This method creates a matrix plot showing relationships between channels, such as coherence, transfer functions, or cross-spectral density.
Parameters¶
plot_type : str, default="matrix" Type of matrix plot to create. **kwargs : dict Additional plot parameters: - vmin, vmax: Color scale limits - cmap: Colormap name - title: Plot title
Returns¶
Union[Axes, Iterator[Axes]] The matplotlib axes containing the plot.
Source code in wandas/frames/spectral.py
658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 | |
info()
¶Display comprehensive information about the SpectralFrame.
This method prints a summary of the frame's properties including: - Number of channels - Sampling rate - FFT size - Frequency range - Number of frequency bins - Frequency resolution (ΔF) - Channel labels
This is a convenience method to view all key properties at once, similar to pandas DataFrame.info().
Examples¶
spectrum = cf.fft() spectrum.info() SpectralFrame Information: Channels: 2 Sampling rate: 44100 Hz FFT size: 2048 Frequency range: 0.0 - 22050.0 Hz Frequency bins: 1025 Frequency resolution (ΔF): 21.5 Hz Channel labels: ['ch0', 'ch1'] Operations Applied: 1
Source code in wandas/frames/spectral.py
698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 | |
spectrogram
¶
Attributes¶
logger = logging.getLogger(__name__)
module-attribute
¶
S = TypeVar('S', bound='BaseFrame[Any]')
module-attribute
¶
Classes¶
SpectrogramFrame
¶
Bases: BaseFrame[NDArrayComplex]
Class for handling time-frequency domain data (spectrograms).
This class represents spectrogram data obtained through Short-Time Fourier Transform (STFT) or similar time-frequency analysis methods. It provides methods for visualization, manipulation, and conversion back to time domain.
Parameters¶
data : DaArray The spectrogram data. Must be a dask array with shape: - (channels, frequency_bins, time_frames) for multi-channel data - (frequency_bins, time_frames) for single-channel data, which will be reshaped to (1, frequency_bins, time_frames) sampling_rate : float The sampling rate of the original time-domain signal in Hz. n_fft : int The FFT size used to generate this spectrogram. hop_length : int Number of samples between successive frames. win_length : int, optional The window length in samples. If None, defaults to n_fft. window : str, default="hann" The window function to use (e.g., "hann", "hamming", "blackman"). label : str, optional A label for the frame. metadata : dict, optional Additional metadata for the frame. operation_history : list[dict], optional History of operations performed on this frame. channel_metadata : list[ChannelMetadata], optional Metadata for each channel in the frame. previous : BaseFrame, optional The frame that this frame was derived from.
Attributes¶
magnitude : NDArrayReal The magnitude spectrogram. phase : NDArrayReal The phase spectrogram in radians. power : NDArrayReal The power spectrogram. dB : NDArrayReal The spectrogram in decibels relative to channel reference values. dBA : NDArrayReal The A-weighted spectrogram in decibels. n_frames : int Number of time frames. n_freq_bins : int Number of frequency bins. freqs : NDArrayReal The frequency axis values in Hz. times : NDArrayReal The time axis values in seconds.
Examples¶
Create a spectrogram from a time-domain signal:
signal = ChannelFrame.from_wav("audio.wav") spectrogram = signal.stft(n_fft=2048, hop_length=512)
Extract a specific time frame:
frame_at_1s = spectrogram.get_frame_at(int(1.0 * sampling_rate / hop_length))
Convert back to time domain:
reconstructed = spectrogram.to_channel_frame()
Plot the spectrogram:
spectrogram.plot()
Source code in wandas/frames/spectrogram.py
27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 | |
n_fft = n_fft
instance-attribute
¶ hop_length = hop_length
instance-attribute
¶ win_length = win_length if win_length is not None else n_fft
instance-attribute
¶ window = window
instance-attribute
¶ magnitude
property
¶ phase
property
¶Get the phase spectrogram.
Returns¶
NDArrayReal The phase angles of the complex spectrogram in radians.
power
property
¶ dB
property
¶Get the spectrogram in decibels relative to each channel's reference value.
The reference value for each channel is specified in its metadata. A minimum value of -120 dB is enforced to avoid numerical issues.
Returns¶
NDArrayReal The spectrogram in decibels.
dBA
property
¶Get the A-weighted spectrogram in decibels.
A-weighting applies a frequency-dependent weighting filter that approximates the human ear's response. This is particularly useful for analyzing noise and acoustic measurements.
Returns¶
NDArrayReal The A-weighted spectrogram in decibels.
n_frames
property
¶ n_freq_bins
property
¶ freqs
property
¶Get the frequency axis values in Hz.
Returns¶
NDArrayReal Array of frequency values corresponding to each frequency bin.
times
property
¶Get the time axis values in seconds.
Returns¶
NDArrayReal Array of time values corresponding to each time frame.
__init__(data, sampling_rate, n_fft, hop_length, win_length=None, window='hann', label=None, metadata=None, operation_history=None, channel_metadata=None, previous=None)
¶Source code in wandas/frames/spectrogram.py
106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 | |
plot(plot_type='spectrogram', ax=None, title=None, cmap='jet', vmin=None, vmax=None, fmin=0, fmax=None, xlim=None, ylim=None, Aw=False, **kwargs)
¶Plot the spectrogram using various visualization strategies.
Parameters¶
plot_type : str, default="spectrogram" Type of plot to create. ax : matplotlib.axes.Axes, optional Axes to plot on. If None, creates new axes. title : str, optional Title for the plot. If None, uses the frame label. cmap : str, default="jet" Colormap name for the spectrogram visualization. vmin : float, optional Minimum value for colormap scaling (dB). Auto-calculated if None. vmax : float, optional Maximum value for colormap scaling (dB). Auto-calculated if None. fmin : float, default=0 Minimum frequency to display (Hz). fmax : float, optional Maximum frequency to display (Hz). If None, uses Nyquist frequency. xlim : tuple[float, float], optional Time axis limits as (start_time, end_time) in seconds. ylim : tuple[float, float], optional Frequency axis limits as (min_freq, max_freq) in Hz. Aw : bool, default=False Whether to apply A-weighting to the spectrogram. **kwargs : dict Additional keyword arguments passed to librosa.display.specshow().
Returns¶
Union[Axes, Iterator[Axes]] The matplotlib axes containing the plot, or an iterator of axes for multi-plot outputs.
Examples¶
stft = cf.stft()
Basic spectrogram¶
stft.plot()
Custom color scale and frequency range¶
stft.plot(vmin=-80, vmax=-20, fmin=100, fmax=5000)
A-weighted spectrogram¶
stft.plot(Aw=True, cmap="viridis")
Source code in wandas/frames/spectrogram.py
449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 | |
plot_Aw(plot_type='spectrogram', ax=None, **kwargs)
¶Plot the A-weighted spectrogram.
A convenience method that calls plot() with Aw=True, applying A-weighting to the spectrogram before plotting.
Parameters¶
plot_type : str, default="spectrogram" Type of plot to create. ax : matplotlib.axes.Axes, optional Axes to plot on. If None, creates new axes. **kwargs : dict Additional keyword arguments passed to plot(). Accepts all parameters from plot() except Aw (which is set to True).
Returns¶
Union[Axes, Iterator[Axes]] The matplotlib axes containing the plot.
Examples¶
stft = cf.stft()
A-weighted spectrogram with custom settings¶
stft.plot_Aw(vmin=-60, vmax=-10, cmap="magma")
Source code in wandas/frames/spectrogram.py
540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 | |
abs()
¶Compute the absolute value (magnitude) of the complex spectrogram.
This method calculates the magnitude of each complex value in the spectrogram, converting the complex-valued data to real-valued magnitude data. The result is stored in a new SpectrogramFrame with complex dtype to maintain compatibility with other spectrogram operations.
Returns¶
SpectrogramFrame A new SpectrogramFrame containing the magnitude values as complex numbers (with zero imaginary parts).
Examples¶
signal = ChannelFrame.from_wav("audio.wav") spectrogram = signal.stft(n_fft=2048, hop_length=512) magnitude_spectrogram = spectrogram.abs()
The magnitude can be accessed via the magnitude property or data¶
print(magnitude_spectrogram.magnitude.shape)
Source code in wandas/frames/spectrogram.py
575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 | |
get_frame_at(time_idx)
¶Extract spectral data at a specific time frame.
Parameters¶
time_idx : int Index of the time frame to extract.
Returns¶
SpectralFrame A new SpectralFrame containing the spectral data at the specified time.
Raises¶
IndexError If time_idx is out of range.
Source code in wandas/frames/spectrogram.py
626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 | |
to_channel_frame()
¶Convert the spectrogram back to time domain using inverse STFT.
This method performs an inverse Short-Time Fourier Transform (ISTFT) to reconstruct the time-domain signal from the spectrogram.
Returns¶
ChannelFrame A new ChannelFrame containing the reconstructed time-domain signal.
See Also¶
istft : Alias for this method with more intuitive naming.
Source code in wandas/frames/spectrogram.py
668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 | |
istft()
¶Convert the spectrogram back to time domain using inverse STFT.
This is an alias for to_channel_frame() with a more intuitive name.
It performs an inverse Short-Time Fourier Transform (ISTFT) to
reconstruct the time-domain signal from the spectrogram.
Returns¶
ChannelFrame A new ChannelFrame containing the reconstructed time-domain signal.
See Also¶
to_channel_frame : The underlying implementation.
Examples¶
signal = ChannelFrame.from_wav("audio.wav") spectrogram = signal.stft(n_fft=2048, hop_length=512) reconstructed = spectrogram.istft()
Source code in wandas/frames/spectrogram.py
716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 | |
to_dataframe()
¶DataFrame conversion is not supported for SpectrogramFrame.
SpectrogramFrame contains 3D data (channels, frequency_bins, time_frames) which cannot be directly converted to a 2D DataFrame. Consider using get_frame_at() to extract a specific time frame as a SpectralFrame, then convert that to a DataFrame.
Raises¶
NotImplementedError Always raised as DataFrame conversion is not supported.
Source code in wandas/frames/spectrogram.py
770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 | |
info()
¶Display comprehensive information about the SpectrogramFrame.
This method prints a summary of the frame's properties including: - Number of channels - Sampling rate - FFT size - Hop length - Window length - Window function - Frequency range - Number of frequency bins - Frequency resolution (ΔF) - Number of time frames - Time resolution (ΔT) - Total duration - Channel labels - Number of operations applied
This is a convenience method to view all key properties at once, similar to pandas DataFrame.info().
Examples¶
signal = ChannelFrame.from_wav("audio.wav") spectrogram = signal.stft(n_fft=2048, hop_length=512) spectrogram.info() SpectrogramFrame Information: Channels: 2 Sampling rate: 44100 Hz FFT size: 2048 Hop length: 512 samples Window length: 2048 samples Window: hann Frequency range: 0.0 - 22050.0 Hz Frequency bins: 1025 Frequency resolution (ΔF): 21.5 Hz Time frames: 100 Time resolution (ΔT): 11.6 ms Total duration: 1.16 s Channel labels: ['ch0', 'ch1'] Operations Applied: 1
Source code in wandas/frames/spectrogram.py
789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 | |
from_numpy(data, sampling_rate, n_fft, hop_length, win_length=None, window='hann', label=None, metadata=None, operation_history=None, channel_metadata=None, previous=None)
classmethod
¶Create a SpectrogramFrame from a NumPy array.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
NDArrayComplex
|
NumPy array containing spectrogram data. Shape should be (n_channels, n_freq_bins, n_time_frames) or (n_freq_bins, n_time_frames) for single channel. |
required |
sampling_rate
|
float
|
The sampling rate in Hz. |
required |
n_fft
|
int
|
The FFT size used to generate this spectrogram. |
required |
hop_length
|
int
|
Number of samples between successive frames. |
required |
win_length
|
int | None
|
The window length in samples. If None, defaults to n_fft. |
None
|
window
|
str
|
The window function used (e.g., "hann", "hamming"). |
'hann'
|
label
|
str | None
|
A label for the frame. |
None
|
metadata
|
dict[str, Any] | None
|
Optional metadata dictionary. |
None
|
operation_history
|
list[dict[str, Any]] | None
|
History of operations applied to the frame. |
None
|
channel_metadata
|
list[ChannelMetadata] | list[dict[str, Any]] | None
|
Metadata for each channel. |
None
|
previous
|
Optional[BaseFrame[Any]]
|
Reference to the previous frame in the processing chain. |
None
|
Returns:
| Type | Description |
|---|---|
SpectrogramFrame
|
A new SpectrogramFrame containing the NumPy data. |
Source code in wandas/frames/spectrogram.py
853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 | |
処理モジュール¶
処理モジュールはオーディオデータに対する様々な処理機能を提供します。
wandas.processing
¶
Audio time series processing operations.
This module provides audio processing operations for time series data.
Attributes¶
__all__ = ['AudioOperation', '_OPERATION_REGISTRY', 'create_operation', 'get_operation', 'register_operation', 'AWeighting', 'HighPassFilter', 'LowPassFilter', 'CSD', 'Coherence', 'FFT', 'IFFT', 'ISTFT', 'NOctSpectrum', 'NOctSynthesis', 'STFT', 'TransferFunction', 'Welch', 'ReSampling', 'RmsTrend', 'Trim', 'AddWithSNR', 'HpssHarmonic', 'HpssPercussive', 'ABS', 'ChannelDifference', 'Mean', 'Power', 'Sum', 'LoudnessZwst', 'LoudnessZwtv']
module-attribute
¶
Classes¶
AudioOperation
¶
Bases: Generic[InputArrayType, OutputArrayType]
Abstract base class for audio processing operations.
Source code in wandas/processing/base.py
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 | |
Attributes¶
name
class-attribute
¶
sampling_rate = sampling_rate
instance-attribute
¶
pure = pure
instance-attribute
¶
params = params
instance-attribute
¶
Functions¶
__init__(sampling_rate, *, pure=True, **params)
¶
Initialize AudioOperation.
Parameters¶
sampling_rate : float Sampling rate (Hz) pure : bool, default=True Whether the operation is pure (deterministic with no side effects). When True, Dask can cache results for identical inputs. Set to False only if the operation has side effects or is non-deterministic. **params : Any Operation-specific parameters
Source code in wandas/processing/base.py
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 | |
validate_params()
¶
Validate parameters (raises exception if invalid)
Source code in wandas/processing/base.py
55 56 57 | |
get_metadata_updates()
¶
Get metadata updates to apply after processing.
This method allows operations to specify how metadata should be updated after processing. By default, no metadata is updated.
Returns¶
dict Dictionary of metadata updates. Can include: - 'sampling_rate': New sampling rate (float) - Other metadata keys as needed
Examples¶
Return empty dict for operations that don't change metadata:
return {}
Return new sampling rate for operations that resample:
return {"sampling_rate": self.target_sr}
Notes¶
This method is called by the framework after processing to update the frame metadata. Subclasses should override this method if they need to update metadata (e.g., changing sampling rate).
Design principle: Operations should use parameters provided at initialization (via init). All necessary information should be available as instance variables.
Source code in wandas/processing/base.py
63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 | |
get_display_name()
¶
Get display name for the operation for use in channel labels.
This method allows operations to customize how they appear in channel labels. By default, returns None, which means the operation name will be used.
Returns¶
str or None
Display name for the operation. If None, the operation name
(from the name class variable) is used.
Examples¶
Default behavior (returns None, uses operation name):
class NormalizeOp(AudioOperation): ... name = "normalize" op = NormalizeOp(44100) op.get_display_name() # Returns None
Channel label: "normalize(ch0)"¶
Custom display name:
class LowPassFilter(AudioOperation): ... name = "lowpass_filter" ... ... def init(self, sr, cutoff): ... self.cutoff = cutoff ... super().init(sr, cutoff=cutoff) ... ... def get_display_name(self): ... return f"lpf_{self.cutoff}Hz" op = LowPassFilter(44100, cutoff=1000) op.get_display_name() # Returns "lpf_1000Hz"
Channel label: "lpf_1000Hz(ch0)"¶
Notes¶
Subclasses can override this method to provide operation-specific display names that include parameter information, making labels more informative.
Source code in wandas/processing/base.py
99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 | |
process_array(x)
¶
Processing function wrapped with @dask.delayed.
This method returns a Delayed object that can be computed later. The operation name is used in the Dask task graph for better visualization.
Parameters¶
x : InputArrayType Input array to process.
Returns¶
dask.delayed.Delayed A Delayed object representing the computation.
Source code in wandas/processing/base.py
168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 | |
calculate_output_shape(input_shape)
¶
Calculate output data shape after operation.
This method can be overridden by subclasses for efficiency. If not overridden, it will execute _process_array on a small test array to determine the output shape.
Parameters¶
input_shape : tuple Input data shape
Returns¶
tuple Output data shape
Notes¶
The default implementation creates a minimal test array and processes it to determine output shape. For performance-critical code, subclasses should override this method with a direct calculation.
Source code in wandas/processing/base.py
191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 | |
process(data)
¶
Execute operation and return result data shape is (channels, samples)
Source code in wandas/processing/base.py
245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 | |
AddWithSNR
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Addition operation considering SNR
Source code in wandas/processing/effects.py
281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 | |
Attributes¶
name = 'add_with_snr'
class-attribute
instance-attribute
¶
other = other
instance-attribute
¶
snr = snr
instance-attribute
¶
Functions¶
__init__(sampling_rate, other, snr=1.0)
¶
Initialize addition operation considering SNR
Parameters¶
sampling_rate : float Sampling rate (Hz) other : DaArray Noise signal to add (channel-frame format) snr : float Signal-to-noise ratio (dB)
Source code in wandas/processing/effects.py
286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 | |
calculate_output_shape(input_shape)
¶
Calculate output data shape after operation
Parameters¶
input_shape : tuple Input data shape
Returns¶
tuple Output data shape (same as input)
Source code in wandas/processing/effects.py
305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 | |
get_display_name()
¶
Get display name for the operation for use in channel labels.
Source code in wandas/processing/effects.py
321 322 323 | |
HpssHarmonic
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
HPSS Harmonic operation
Source code in wandas/processing/effects.py
17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 | |
Attributes¶
name = 'hpss_harmonic'
class-attribute
instance-attribute
¶
kwargs = kwargs
instance-attribute
¶
Functions¶
__init__(sampling_rate, **kwargs)
¶
Initialize HPSS Harmonic
Parameters¶
sampling_rate : float Sampling rate (Hz)
Source code in wandas/processing/effects.py
22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 | |
calculate_output_shape(input_shape)
¶
Source code in wandas/processing/effects.py
38 39 | |
get_display_name()
¶
Get display name for the operation for use in channel labels.
Source code in wandas/processing/effects.py
41 42 43 | |
HpssPercussive
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
HPSS Percussive operation
Source code in wandas/processing/effects.py
55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 | |
Attributes¶
name = 'hpss_percussive'
class-attribute
instance-attribute
¶
kwargs = kwargs
instance-attribute
¶
Functions¶
__init__(sampling_rate, **kwargs)
¶
Initialize HPSS Percussive
Parameters¶
sampling_rate : float Sampling rate (Hz)
Source code in wandas/processing/effects.py
60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 | |
calculate_output_shape(input_shape)
¶
Source code in wandas/processing/effects.py
76 77 | |
get_display_name()
¶
Get display name for the operation for use in channel labels.
Source code in wandas/processing/effects.py
79 80 81 | |
AWeighting
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
A-weighting filter operation
Source code in wandas/processing/filters.py
261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 | |
Attributes¶
name = 'a_weighting'
class-attribute
instance-attribute
¶
Functions¶
__init__(sampling_rate)
¶
Initialize A-weighting filter
Parameters¶
sampling_rate : float Sampling rate (Hz)
Source code in wandas/processing/filters.py
266 267 268 269 270 271 272 273 274 275 | |
calculate_output_shape(input_shape)
¶
Source code in wandas/processing/filters.py
277 278 | |
get_display_name()
¶
Get display name for the operation for use in channel labels.
Source code in wandas/processing/filters.py
280 281 282 | |
HighPassFilter
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
High-pass filter operation
Source code in wandas/processing/filters.py
13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 | |
Attributes¶
name = 'highpass_filter'
class-attribute
instance-attribute
¶
a
instance-attribute
¶
b
instance-attribute
¶
cutoff = cutoff
instance-attribute
¶
order = order
instance-attribute
¶
Functions¶
__init__(sampling_rate, cutoff, order=4)
¶
Initialize high-pass filter
Parameters¶
sampling_rate : float Sampling rate (Hz) cutoff : float Cutoff frequency (Hz). Must be between 0 and Nyquist frequency (sampling_rate / 2). order : int, optional Filter order, default is 4
Raises¶
ValueError If cutoff frequency is not within valid range (0 < cutoff < Nyquist)
Source code in wandas/processing/filters.py
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 | |
validate_params()
¶
Validate parameters
Source code in wandas/processing/filters.py
43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 | |
calculate_output_shape(input_shape)
¶
Source code in wandas/processing/filters.py
70 71 | |
get_display_name()
¶
Get display name for the operation for use in channel labels.
Source code in wandas/processing/filters.py
73 74 75 | |
LowPassFilter
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Low-pass filter operation
Source code in wandas/processing/filters.py
85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 | |
Attributes¶
name = 'lowpass_filter'
class-attribute
instance-attribute
¶
a
instance-attribute
¶
b
instance-attribute
¶
cutoff = cutoff
instance-attribute
¶
order = order
instance-attribute
¶
Functions¶
__init__(sampling_rate, cutoff, order=4)
¶
Initialize low-pass filter
Parameters¶
sampling_rate : float Sampling rate (Hz) cutoff : float Cutoff frequency (Hz). Must be between 0 and Nyquist frequency (sampling_rate / 2). order : int, optional Filter order, default is 4
Raises¶
ValueError If cutoff frequency is not within valid range (0 < cutoff < Nyquist)
Source code in wandas/processing/filters.py
92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 | |
validate_params()
¶
Validate parameters
Source code in wandas/processing/filters.py
115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 | |
calculate_output_shape(input_shape)
¶
Source code in wandas/processing/filters.py
141 142 | |
get_display_name()
¶
Get display name for the operation for use in channel labels.
Source code in wandas/processing/filters.py
144 145 146 | |
LoudnessZwst
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Calculate steady-state loudness using Zwicker method (ISO 532-1:2017).
This operation computes the loudness of stationary (steady) signals according to the Zwicker method, as specified in ISO 532-1:2017. It uses the MoSQITo library's implementation of the standardized loudness calculation for steady signals.
The loudness is calculated in sones, a unit of perceived loudness where a doubling of sones corresponds to a doubling of perceived loudness.
Parameters¶
sampling_rate : float Sampling rate in Hz. The signal should be sampled at a rate appropriate for the analysis (typically 44100 Hz or 48000 Hz for audio). field_type : str, default="free" Type of sound field. Options: - 'free': Free field (sound arriving from a specific direction) - 'diffuse': Diffuse field (sound arriving uniformly from all directions)
Attributes¶
name : str Operation name: "loudness_zwst" field_type : str The sound field type used for calculation
Examples¶
Calculate steady-state loudness for a signal:
import wandas as wd signal = wd.read_wav("fan_noise.wav") loudness = signal.loudness_zwst(field_type="free") print(f"Steady-state loudness: {loudness.data[0]:.2f} sones")
Notes¶
- The output contains a single loudness value in sones for each channel
- For mono signals, the loudness is calculated directly
- For multi-channel signals, loudness is calculated per channel
- The method follows ISO 532-1:2017 standard for steady-state loudness
- Typical loudness values: 1 sone ≈ 40 phon (loudness level)
- This method is suitable for stationary signals such as fan noise, constant machinery sounds, or other steady sounds
References¶
.. [1] ISO 532-1:2017, "Acoustics — Methods for calculating loudness — Part 1: Zwicker method" .. [2] MoSQITo documentation: https://mosqito.readthedocs.io/en/latest/
Source code in wandas/processing/psychoacoustic.py
223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 | |
Attributes¶
name = 'loudness_zwst'
class-attribute
instance-attribute
¶
field_type = field_type
instance-attribute
¶
Functions¶
__init__(sampling_rate, field_type='free')
¶
Initialize steady-state loudness calculation operation.
Parameters¶
sampling_rate : float Sampling rate (Hz) field_type : str, default="free" Type of sound field ('free' or 'diffuse')
Source code in wandas/processing/psychoacoustic.py
279 280 281 282 283 284 285 286 287 288 289 290 291 | |
validate_params()
¶
Validate parameters.
Raises¶
ValueError If field_type is not 'free' or 'diffuse'
Source code in wandas/processing/psychoacoustic.py
293 294 295 296 297 298 299 300 301 302 303 304 305 | |
get_metadata_updates()
¶
Get metadata updates to apply after processing.
For steady-state loudness, the output is a single value per channel, so no sampling rate update is needed (output is scalar, not time-series).
Returns¶
dict Empty dictionary (no metadata updates needed)
Notes¶
Unlike time-varying loudness, steady-state loudness produces a single value, not a time series, so the sampling rate concept doesn't apply.
Source code in wandas/processing/psychoacoustic.py
307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 | |
calculate_output_shape(input_shape)
¶
Calculate output data shape after operation.
The steady-state loudness calculation produces a single loudness value per channel.
Parameters¶
input_shape : tuple Input data shape (channels, samples)
Returns¶
tuple Output data shape: (channels, 1) - one loudness value per channel
Source code in wandas/processing/psychoacoustic.py
326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 | |
LoudnessZwtv
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Calculate time-varying loudness using Zwicker method (ISO 532-1:2017).
This operation computes the loudness of non-stationary signals according to the Zwicker method, as specified in ISO 532-1:2017. It uses the MoSQITo library's implementation of the standardized loudness calculation.
The loudness is calculated in sones, a unit of perceived loudness where a doubling of sones corresponds to a doubling of perceived loudness.
Parameters¶
sampling_rate : float Sampling rate in Hz. The signal should be sampled at a rate appropriate for the analysis (typically 44100 Hz or 48000 Hz for audio). field_type : str, default="free" Type of sound field. Options: - 'free': Free field (sound arriving from a specific direction) - 'diffuse': Diffuse field (sound arriving uniformly from all directions)
Attributes¶
name : str Operation name: "loudness_zwtv" field_type : str The sound field type used for calculation
Examples¶
Calculate loudness for a signal:
import wandas as wd signal = wd.read_wav("audio.wav") loudness = signal.loudness_zwtv(field_type="free")
Notes¶
- The output contains time-varying loudness values in sones
- For mono signals, the loudness is calculated directly
- For multi-channel signals, loudness is calculated per channel
- The method follows ISO 532-1:2017 standard for time-varying loudness
- Typical loudness values: 1 sone ≈ 40 phon (loudness level)
References¶
.. [1] ISO 532-1:2017, "Acoustics — Methods for calculating loudness — Part 1: Zwicker method" .. [2] MoSQITo documentation: https://mosqito.readthedocs.io/en/latest/
Source code in wandas/processing/psychoacoustic.py
24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 | |
Attributes¶
name = 'loudness_zwtv'
class-attribute
instance-attribute
¶
field_type = field_type
instance-attribute
¶
Functions¶
__init__(sampling_rate, field_type='free')
¶
Initialize Loudness calculation operation.
Parameters¶
sampling_rate : float Sampling rate (Hz) field_type : str, default="free" Type of sound field ('free' or 'diffuse')
Source code in wandas/processing/psychoacoustic.py
77 78 79 80 81 82 83 84 85 86 87 88 89 | |
validate_params()
¶
Validate parameters.
Raises¶
ValueError If field_type is not 'free' or 'diffuse'
Source code in wandas/processing/psychoacoustic.py
91 92 93 94 95 96 97 98 99 100 101 102 103 | |
get_metadata_updates()
¶
Update sampling rate based on MoSQITo's time resolution.
The Zwicker method uses approximately 2ms time steps, which corresponds to 500 Hz sampling rate, independent of the input sampling rate.
Returns¶
dict Metadata updates with new sampling rate
Notes¶
All necessary parameters are provided at initialization. The output sampling rate is always 500 Hz regardless of input.
Source code in wandas/processing/psychoacoustic.py
105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 | |
calculate_output_shape(input_shape)
¶
Calculate output data shape after operation.
The loudness calculation produces a time-varying output where the time resolution depends on the algorithm's internal processing. The exact output length is determined dynamically by the loudness_zwtv function.
Parameters¶
input_shape : tuple Input data shape (channels, samples)
Returns¶
tuple Output data shape. For loudness, we return a placeholder shape since the actual length is determined by the algorithm. The shape will be (channels, time_samples) where time_samples depends on the input length and algorithm parameters.
Source code in wandas/processing/psychoacoustic.py
125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 | |
CSD
¶
Bases: AudioOperation[NDArrayReal, NDArrayComplex]
Cross-spectral density estimation operation
Source code in wandas/processing/spectral.py
930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 | |
Attributes¶
name = 'csd'
class-attribute
instance-attribute
¶
n_fft = n_fft
instance-attribute
¶
win_length = actual_win_length
instance-attribute
¶
hop_length = actual_hop_length
instance-attribute
¶
window = window
instance-attribute
¶
detrend = detrend
instance-attribute
¶
scaling = scaling
instance-attribute
¶
average = average
instance-attribute
¶
Functions¶
__init__(sampling_rate, n_fft=2048, hop_length=None, win_length=None, window='hann', detrend='constant', scaling='spectrum', average='mean')
¶
Initialize cross-spectral density estimation operation
Parameters¶
sampling_rate : float Sampling rate (Hz) n_fft : int FFT size, default is 2048 hop_length : int, optional Number of samples between frames. Default is win_length // 4 win_length : int, optional Window length. Default is n_fft window : str Window function, default is 'hann' detrend : str Type of detrend, default is 'constant' scaling : str Type of scaling, default is 'spectrum' average : str Method of averaging, default is 'mean'
Raises¶
ValueError If n_fft is not positive, win_length > n_fft, or hop_length is invalid
Source code in wandas/processing/spectral.py
935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 | |
calculate_output_shape(input_shape)
¶
Calculate output data shape after operation
Parameters¶
input_shape : tuple Input data shape (channels, samples)
Returns¶
tuple Output data shape (channels * channels, freqs)
Source code in wandas/processing/spectral.py
996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 | |
get_display_name()
¶
Get display name for the operation for use in channel labels.
Source code in wandas/processing/spectral.py
1014 1015 1016 | |
FFT
¶
Bases: AudioOperation[NDArrayReal, NDArrayComplex]
FFT (Fast Fourier Transform) operation
Source code in wandas/processing/spectral.py
116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 | |
Attributes¶
name = 'fft'
class-attribute
instance-attribute
¶
n_fft = n_fft
instance-attribute
¶
window = window
instance-attribute
¶
Functions¶
__init__(sampling_rate, n_fft=None, window='hann')
¶
Initialize FFT operation
Parameters¶
sampling_rate : float Sampling rate (Hz) n_fft : int, optional FFT size, default is None (determined by input size) window : str, optional Window function type, default is 'hann'
Raises¶
ValueError If n_fft is not a positive integer
Source code in wandas/processing/spectral.py
123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 | |
calculate_output_shape(input_shape)
¶
操作後の出力データの形状を計算します
Parameters¶
input_shape : tuple 入力データの形状 (channels, samples)
Returns¶
tuple 出力データの形状 (channels, freqs)
Source code in wandas/processing/spectral.py
158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 | |
get_display_name()
¶
Get display name for the operation for use in channel labels.
Source code in wandas/processing/spectral.py
175 176 177 | |
IFFT
¶
Bases: AudioOperation[NDArrayComplex, NDArrayReal]
IFFT (Inverse Fast Fourier Transform) operation
Source code in wandas/processing/spectral.py
197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 | |
Attributes¶
name = 'ifft'
class-attribute
instance-attribute
¶
n_fft = n_fft
instance-attribute
¶
window = window
instance-attribute
¶
Functions¶
__init__(sampling_rate, n_fft=None, window='hann')
¶
Initialize IFFT operation
Parameters¶
sampling_rate : float Sampling rate (Hz) n_fft : Optional[int], optional IFFT size, default is None (determined based on input size) window : str, optional Window function type, default is 'hann'
Source code in wandas/processing/spectral.py
204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 | |
calculate_output_shape(input_shape)
¶
Calculate output data shape after operation
Parameters¶
input_shape : tuple Input data shape (channels, freqs)
Returns¶
tuple Output data shape (channels, samples)
Source code in wandas/processing/spectral.py
223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 | |
get_display_name()
¶
Get display name for the operation for use in channel labels.
Source code in wandas/processing/spectral.py
240 241 242 | |
ISTFT
¶
Bases: AudioOperation[NDArrayComplex, NDArrayReal]
Inverse Short-Time Fourier Transform operation
Source code in wandas/processing/spectral.py
368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 | |
Attributes¶
name = 'istft'
class-attribute
instance-attribute
¶
n_fft = n_fft
instance-attribute
¶
win_length = actual_win_length
instance-attribute
¶
hop_length = actual_hop_length
instance-attribute
¶
window = window
instance-attribute
¶
length = length
instance-attribute
¶
SFT = ShortTimeFFT(win=(get_window(window, self.win_length)), hop=(self.hop_length), fs=sampling_rate, mfft=(self.n_fft), scale_to='magnitude')
instance-attribute
¶
Functions¶
__init__(sampling_rate, n_fft=2048, hop_length=None, win_length=None, window='hann', length=None)
¶
Initialize ISTFT operation
Parameters¶
sampling_rate : float Sampling rate (Hz) n_fft : int FFT size, default is 2048 hop_length : int, optional Number of samples between frames. Default is win_length // 4 win_length : int, optional Window length. Default is n_fft window : str Window type, default is 'hann' length : int, optional Length of output signal. Default is None (determined from input)
Raises¶
ValueError If n_fft is not positive, win_length > n_fft, or hop_length is invalid
Source code in wandas/processing/spectral.py
373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 | |
calculate_output_shape(input_shape)
¶
Calculate output data shape after ISTFT operation.
Uses the SciPy ShortTimeFFT calculation formula to compute the expected output length based on the input spectrogram dimensions and output range parameters (k0, k1).
Parameters¶
input_shape : tuple Input spectrogram shape (channels, n_freqs, n_frames) where n_freqs = n_fft // 2 + 1 and n_frames is the number of time frames.
Returns¶
tuple Output shape (channels, output_samples) where output_samples is the reconstructed signal length determined by the output range [k0, k1).
Notes¶
The calculation follows SciPy's ShortTimeFFT.istft() implementation. When k1 is None (default), the maximum reconstructible signal length is computed as:
.. math::
q_{max} = n_{frames} + p_{min}
k_{max} = (q_{max} - 1) \cdot hop + m_{num} - m_{num\_mid}
The output length is then:
.. math::
output\_samples = k_1 - k_0
where k0 defaults to 0 and k1 defaults to k_max.
Parameters that affect the calculation: - n_frames: number of time frames in the STFT - p_min: minimum frame index (ShortTimeFFT property) - hop: hop length (samples between frames) - m_num: window length - m_num_mid: window midpoint position - self.length: optional length override (if set, limits output)
References¶
- SciPy ShortTimeFFT.istft: https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.ShortTimeFFT.istft.html
- SciPy Source: https://github.com/scipy/scipy/blob/main/scipy/signal/_short_time_fft.py
Source code in wandas/processing/spectral.py
434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 | |
get_display_name()
¶
Get display name for the operation for use in channel labels.
Source code in wandas/processing/spectral.py
509 510 511 | |
STFT
¶
Bases: AudioOperation[NDArrayReal, NDArrayComplex]
Short-Time Fourier Transform operation
Source code in wandas/processing/spectral.py
268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 | |
Attributes¶
name = 'stft'
class-attribute
instance-attribute
¶
n_fft = n_fft
instance-attribute
¶
win_length = actual_win_length
instance-attribute
¶
hop_length = actual_hop_length
instance-attribute
¶
noverlap = self.win_length - self.hop_length if hop_length is not None else None
instance-attribute
¶
window = window
instance-attribute
¶
SFT = ShortTimeFFT(win=(get_window(window, self.win_length)), hop=(self.hop_length), fs=sampling_rate, mfft=(self.n_fft), scale_to='magnitude')
instance-attribute
¶
Functions¶
__init__(sampling_rate, n_fft=2048, hop_length=None, win_length=None, window='hann')
¶
Initialize STFT operation
Parameters¶
sampling_rate : float Sampling rate (Hz) n_fft : int FFT size, default is 2048 hop_length : int, optional Number of samples between frames. Default is win_length // 4 win_length : int, optional Window length. Default is n_fft window : str Window type, default is 'hann'
Raises¶
ValueError If n_fft is not positive, win_length > n_fft, or hop_length is invalid
Source code in wandas/processing/spectral.py
273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 | |
calculate_output_shape(input_shape)
¶
Calculate output data shape after operation
Parameters¶
input_shape : tuple Input data shape
Returns¶
tuple Output data shape
Source code in wandas/processing/spectral.py
330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 | |
get_display_name()
¶
Get display name for the operation for use in channel labels.
Source code in wandas/processing/spectral.py
349 350 351 | |
Coherence
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Coherence estimation operation
Source code in wandas/processing/spectral.py
829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 | |
Attributes¶
name = 'coherence'
class-attribute
instance-attribute
¶
n_fft = n_fft
instance-attribute
¶
win_length = actual_win_length
instance-attribute
¶
hop_length = actual_hop_length
instance-attribute
¶
window = window
instance-attribute
¶
detrend = detrend
instance-attribute
¶
Functions¶
__init__(sampling_rate, n_fft=2048, hop_length=None, win_length=None, window='hann', detrend='constant')
¶
Initialize coherence estimation operation
Parameters¶
sampling_rate : float Sampling rate (Hz) n_fft : int FFT size, default is 2048 hop_length : int, optional Number of samples between frames. Default is win_length // 4 win_length : int, optional Window length. Default is n_fft window : str Window function, default is 'hann' detrend : str Type of detrend, default is 'constant'
Raises¶
ValueError If n_fft is not positive, win_length > n_fft, or hop_length is invalid
Source code in wandas/processing/spectral.py
834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 | |
calculate_output_shape(input_shape)
¶
Calculate output data shape after operation
Parameters¶
input_shape : tuple Input data shape (channels, samples)
Returns¶
tuple Output data shape (channels * channels, freqs)
Source code in wandas/processing/spectral.py
885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 | |
get_display_name()
¶
Get display name for the operation for use in channel labels.
Source code in wandas/processing/spectral.py
903 904 905 | |
NOctSpectrum
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
N-octave spectrum operation
Source code in wandas/processing/spectral.py
655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 | |
Attributes¶
name = 'noct_spectrum'
class-attribute
instance-attribute
¶
fmin = fmin
instance-attribute
¶
fmax = fmax
instance-attribute
¶
n = n
instance-attribute
¶
G = G
instance-attribute
¶
fr = fr
instance-attribute
¶
Functions¶
__init__(sampling_rate, fmin, fmax, n=3, G=10, fr=1000)
¶
Initialize N-octave spectrum
Parameters¶
sampling_rate : float Sampling rate (Hz) fmin : float Minimum frequency (Hz) fmax : float Maximum frequency (Hz) n : int, optional Number of octave divisions, default is 3 G : int, optional Reference level, default is 10 fr : int, optional Reference frequency, default is 1000
Source code in wandas/processing/spectral.py
660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 | |
calculate_output_shape(input_shape)
¶
Calculate output data shape after operation
Parameters¶
input_shape : tuple Input data shape
Returns¶
tuple Output data shape
Source code in wandas/processing/spectral.py
694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 | |
get_display_name()
¶
Get display name for the operation for use in channel labels.
Source code in wandas/processing/spectral.py
714 715 716 | |
NOctSynthesis
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Octave synthesis operation
Source code in wandas/processing/spectral.py
739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 | |
Attributes¶
name = 'noct_synthesis'
class-attribute
instance-attribute
¶
fmin = fmin
instance-attribute
¶
fmax = fmax
instance-attribute
¶
n = n
instance-attribute
¶
G = G
instance-attribute
¶
fr = fr
instance-attribute
¶
Functions¶
__init__(sampling_rate, fmin, fmax, n=3, G=10, fr=1000)
¶
Initialize octave synthesis
Parameters¶
sampling_rate : float Sampling rate (Hz) fmin : float Minimum frequency (Hz) fmax : float Maximum frequency (Hz) n : int, optional Number of octave divisions, default is 3 G : int, optional Reference level, default is 10 fr : int, optional Reference frequency, default is 1000
Source code in wandas/processing/spectral.py
744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 | |
calculate_output_shape(input_shape)
¶
Calculate output data shape after operation
Parameters¶
input_shape : tuple Input data shape
Returns¶
tuple Output data shape
Source code in wandas/processing/spectral.py
779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 | |
get_display_name()
¶
Get display name for the operation for use in channel labels.
Source code in wandas/processing/spectral.py
799 800 801 | |
TransferFunction
¶
Bases: AudioOperation[NDArrayReal, NDArrayComplex]
Transfer function estimation operation
Source code in wandas/processing/spectral.py
1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 | |
Attributes¶
name = 'transfer_function'
class-attribute
instance-attribute
¶
n_fft = n_fft
instance-attribute
¶
win_length = actual_win_length
instance-attribute
¶
hop_length = actual_hop_length
instance-attribute
¶
window = window
instance-attribute
¶
detrend = detrend
instance-attribute
¶
scaling = scaling
instance-attribute
¶
average = average
instance-attribute
¶
Functions¶
__init__(sampling_rate, n_fft=2048, hop_length=None, win_length=None, window='hann', detrend='constant', scaling='spectrum', average='mean')
¶
Initialize transfer function estimation operation
Parameters¶
sampling_rate : float Sampling rate (Hz) n_fft : int FFT size, default is 2048 hop_length : int, optional Number of samples between frames. Default is win_length // 4 win_length : int, optional Window length. Default is n_fft window : str Window function, default is 'hann' detrend : str Type of detrend, default is 'constant' scaling : str Type of scaling, default is 'spectrum' average : str Method of averaging, default is 'mean'
Raises¶
ValueError If n_fft is not positive, win_length > n_fft, or hop_length is invalid
Source code in wandas/processing/spectral.py
1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 | |
calculate_output_shape(input_shape)
¶
Calculate output data shape after operation
Parameters¶
input_shape : tuple Input data shape (channels, samples)
Returns¶
tuple Output data shape (channels * channels, freqs)
Source code in wandas/processing/spectral.py
1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 | |
get_display_name()
¶
Get display name for the operation for use in channel labels.
Source code in wandas/processing/spectral.py
1130 1131 1132 | |
Welch
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Welch
Source code in wandas/processing/spectral.py
541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 | |
Attributes¶
name = 'welch'
class-attribute
instance-attribute
¶
n_fft = n_fft
instance-attribute
¶
window = window
instance-attribute
¶
hop_length = actual_hop_length
instance-attribute
¶
win_length = actual_win_length
instance-attribute
¶
average = average
instance-attribute
¶
detrend = detrend
instance-attribute
¶
noverlap = self.win_length - self.hop_length if hop_length is not None else None
instance-attribute
¶
Functions¶
__init__(sampling_rate, n_fft=2048, hop_length=None, win_length=None, window='hann', average='mean', detrend='constant')
¶
Initialize Welch operation
Parameters¶
sampling_rate : float Sampling rate (Hz) n_fft : int, optional FFT size, default is 2048 hop_length : int, optional Number of samples between frames. Default is win_length // 4 win_length : int, optional Window length. Default is n_fft window : str, optional Window function type, default is 'hann' average : str, optional Averaging method, default is 'mean' detrend : str, optional Detrend method, default is 'constant'
Raises¶
ValueError If n_fft, win_length, or hop_length are invalid
Source code in wandas/processing/spectral.py
552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 | |
calculate_output_shape(input_shape)
¶
Calculate output data shape after operation
Parameters¶
input_shape : tuple Input data shape (channels, samples)
Returns¶
tuple Output data shape (channels, freqs)
Source code in wandas/processing/spectral.py
611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 | |
get_display_name()
¶
Get display name for the operation for use in channel labels.
Source code in wandas/processing/spectral.py
628 629 630 | |
ABS
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Absolute value operation
Source code in wandas/processing/stats.py
12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 | |
Attributes¶
name = 'abs'
class-attribute
instance-attribute
¶
Functions¶
__init__(sampling_rate)
¶
Initialize absolute value operation
Parameters¶
sampling_rate : float Sampling rate (Hz)
Source code in wandas/processing/stats.py
17 18 19 20 21 22 23 24 25 26 | |
get_display_name()
¶
Get display name for the operation for use in channel labels.
Source code in wandas/processing/stats.py
28 29 30 | |
process(data)
¶
Source code in wandas/processing/stats.py
32 33 34 | |
ChannelDifference
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Channel difference calculation operation
Source code in wandas/processing/stats.py
93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 | |
Attributes¶
name = 'channel_difference'
class-attribute
instance-attribute
¶
other_channel = other_channel
instance-attribute
¶
Functions¶
__init__(sampling_rate, other_channel=0)
¶
Initialize channel difference calculation
Parameters¶
sampling_rate : float Sampling rate (Hz) other_channel : int Channel to calculate difference with, default is 0
Source code in wandas/processing/stats.py
99 100 101 102 103 104 105 106 107 108 109 110 111 | |
get_display_name()
¶
Get display name for the operation for use in channel labels.
Source code in wandas/processing/stats.py
113 114 115 | |
process(data)
¶
Source code in wandas/processing/stats.py
117 118 119 120 | |
Mean
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Mean calculation
Source code in wandas/processing/stats.py
79 80 81 82 83 84 85 86 87 88 89 90 | |
Attributes¶
name = 'mean'
class-attribute
instance-attribute
¶
Functions¶
get_display_name()
¶
Get display name for the operation for use in channel labels.
Source code in wandas/processing/stats.py
84 85 86 | |
process(data)
¶
Source code in wandas/processing/stats.py
88 89 90 | |
Power
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Power operation
Source code in wandas/processing/stats.py
37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 | |
Attributes¶
name = 'power'
class-attribute
instance-attribute
¶
exp = exponent
instance-attribute
¶
Functions¶
__init__(sampling_rate, exponent)
¶
Initialize power operation
Parameters¶
sampling_rate : float Sampling rate (Hz) exponent : float Power exponent
Source code in wandas/processing/stats.py
42 43 44 45 46 47 48 49 50 51 52 53 54 | |
get_display_name()
¶
Get display name for the operation for use in channel labels.
Source code in wandas/processing/stats.py
56 57 58 | |
process(data)
¶
Source code in wandas/processing/stats.py
60 61 62 | |
Sum
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Sum calculation
Source code in wandas/processing/stats.py
65 66 67 68 69 70 71 72 73 74 75 76 | |
Attributes¶
name = 'sum'
class-attribute
instance-attribute
¶
Functions¶
get_display_name()
¶
Get display name for the operation for use in channel labels.
Source code in wandas/processing/stats.py
70 71 72 | |
process(data)
¶
Source code in wandas/processing/stats.py
74 75 76 | |
ReSampling
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Resampling operation
Source code in wandas/processing/temporal.py
15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 | |
Attributes¶
name = 'resampling'
class-attribute
instance-attribute
¶
target_sr = target_sr
instance-attribute
¶
Functions¶
__init__(sampling_rate, target_sr)
¶
Initialize resampling operation
Parameters¶
sampling_rate : float Sampling rate (Hz) target_sampling_rate : float Target sampling rate (Hz)
Raises¶
ValueError If sampling_rate or target_sr is not positive
Source code in wandas/processing/temporal.py
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 | |
get_metadata_updates()
¶
Update sampling rate to target sampling rate.
Returns¶
dict Metadata updates with new sampling rate
Notes¶
Resampling always produces output at target_sr, regardless of input sampling rate. All necessary parameters are provided at initialization.
Source code in wandas/processing/temporal.py
41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 | |
calculate_output_shape(input_shape)
¶
Calculate output data shape after operation
Parameters¶
input_shape : tuple Input data shape
Returns¶
tuple Output data shape
Source code in wandas/processing/temporal.py
57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 | |
get_display_name()
¶
Get display name for the operation for use in channel labels.
Source code in wandas/processing/temporal.py
76 77 78 | |
RmsTrend
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
RMS calculation
Source code in wandas/processing/temporal.py
220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 | |
Attributes¶
name = 'rms_trend'
class-attribute
instance-attribute
¶
frame_length = frame_length
instance-attribute
¶
hop_length = hop_length
instance-attribute
¶
Aw = Aw
instance-attribute
¶
dB = dB
instance-attribute
¶
ref = np.array(ref if isinstance(ref, list) else [ref])
instance-attribute
¶
Functions¶
__init__(sampling_rate, frame_length=2048, hop_length=512, ref=1.0, dB=False, Aw=False)
¶
Initialize RMS calculation
Parameters¶
sampling_rate : float Sampling rate (Hz) frame_length : int Frame length, default is 2048 hop_length : int Hop length, default is 512 ref : Union[list[float], float] Reference value(s) for dB calculation dB : bool Whether to convert to decibels Aw : bool Whether to apply A-weighting before RMS calculation
Source code in wandas/processing/temporal.py
228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 | |
get_metadata_updates()
¶
Update sampling rate based on hop length.
Returns¶
dict Metadata updates with new sampling rate based on hop length
Notes¶
The output sampling rate is determined by downsampling the input by hop_length. All necessary parameters are provided at initialization.
Source code in wandas/processing/temporal.py
269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 | |
calculate_output_shape(input_shape)
¶
Calculate output data shape after operation
Parameters¶
input_shape : tuple Input data shape (channels, samples)
Returns¶
tuple Output data shape (channels, frames)
Source code in wandas/processing/temporal.py
286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 | |
get_display_name()
¶
Get display name for the operation for use in channel labels.
Source code in wandas/processing/temporal.py
307 308 309 | |
Trim
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Trimming operation
Source code in wandas/processing/temporal.py
90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 | |
Attributes¶
name = 'trim'
class-attribute
instance-attribute
¶
start = start
instance-attribute
¶
end = end
instance-attribute
¶
start_sample = int(start * sampling_rate)
instance-attribute
¶
end_sample = int(end * sampling_rate)
instance-attribute
¶
Functions¶
__init__(sampling_rate, start, end)
¶
Initialize trimming operation
Parameters¶
sampling_rate : float Sampling rate (Hz) start : float Start time for trimming (seconds) end : float End time for trimming (seconds)
Source code in wandas/processing/temporal.py
95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 | |
calculate_output_shape(input_shape)
¶
Calculate output data shape after operation
Parameters¶
input_shape : tuple Input data shape
Returns¶
tuple Output data shape
Source code in wandas/processing/temporal.py
122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 | |
get_display_name()
¶
Get display name for the operation for use in channel labels.
Source code in wandas/processing/temporal.py
142 143 144 | |
Functions¶
create_operation(name, sampling_rate, **params)
¶
Create operation instance from name and parameters
Source code in wandas/processing/base.py
286 287 288 289 290 291 | |
get_operation(name)
¶
Get operation class by name
Source code in wandas/processing/base.py
279 280 281 282 283 | |
register_operation(operation_class)
¶
Register a new operation type
Source code in wandas/processing/base.py
268 269 270 271 272 273 274 275 276 | |
Modules¶
base
¶
Attributes¶
logger = logging.getLogger(__name__)
module-attribute
¶
InputArrayType = TypeVar('InputArrayType', NDArrayReal, NDArrayComplex)
module-attribute
¶
OutputArrayType = TypeVar('OutputArrayType', NDArrayReal, NDArrayComplex)
module-attribute
¶
Classes¶
AudioOperation
¶
Bases: Generic[InputArrayType, OutputArrayType]
Abstract base class for audio processing operations.
Source code in wandas/processing/base.py
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 | |
name
class-attribute
¶ sampling_rate = sampling_rate
instance-attribute
¶ pure = pure
instance-attribute
¶ params = params
instance-attribute
¶ __init__(sampling_rate, *, pure=True, **params)
¶Initialize AudioOperation.
Parameters¶
sampling_rate : float Sampling rate (Hz) pure : bool, default=True Whether the operation is pure (deterministic with no side effects). When True, Dask can cache results for identical inputs. Set to False only if the operation has side effects or is non-deterministic. **params : Any Operation-specific parameters
Source code in wandas/processing/base.py
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 | |
validate_params()
¶Validate parameters (raises exception if invalid)
Source code in wandas/processing/base.py
55 56 57 | |
get_metadata_updates()
¶Get metadata updates to apply after processing.
This method allows operations to specify how metadata should be updated after processing. By default, no metadata is updated.
Returns¶
dict Dictionary of metadata updates. Can include: - 'sampling_rate': New sampling rate (float) - Other metadata keys as needed
Examples¶
Return empty dict for operations that don't change metadata:
return {}
Return new sampling rate for operations that resample:
return {"sampling_rate": self.target_sr}
Notes¶
This method is called by the framework after processing to update the frame metadata. Subclasses should override this method if they need to update metadata (e.g., changing sampling rate).
Design principle: Operations should use parameters provided at initialization (via init). All necessary information should be available as instance variables.
Source code in wandas/processing/base.py
63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 | |
get_display_name()
¶Get display name for the operation for use in channel labels.
This method allows operations to customize how they appear in channel labels. By default, returns None, which means the operation name will be used.
Returns¶
str or None
Display name for the operation. If None, the operation name
(from the name class variable) is used.
Examples¶
Default behavior (returns None, uses operation name):
class NormalizeOp(AudioOperation): ... name = "normalize" op = NormalizeOp(44100) op.get_display_name() # Returns None
Channel label: "normalize(ch0)"¶
Custom display name:
class LowPassFilter(AudioOperation): ... name = "lowpass_filter" ... ... def init(self, sr, cutoff): ... self.cutoff = cutoff ... super().init(sr, cutoff=cutoff) ... ... def get_display_name(self): ... return f"lpf_{self.cutoff}Hz" op = LowPassFilter(44100, cutoff=1000) op.get_display_name() # Returns "lpf_1000Hz"
Channel label: "lpf_1000Hz(ch0)"¶
Notes¶
Subclasses can override this method to provide operation-specific display names that include parameter information, making labels more informative.
Source code in wandas/processing/base.py
99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 | |
process_array(x)
¶Processing function wrapped with @dask.delayed.
This method returns a Delayed object that can be computed later. The operation name is used in the Dask task graph for better visualization.
Parameters¶
x : InputArrayType Input array to process.
Returns¶
dask.delayed.Delayed A Delayed object representing the computation.
Source code in wandas/processing/base.py
168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 | |
calculate_output_shape(input_shape)
¶Calculate output data shape after operation.
This method can be overridden by subclasses for efficiency. If not overridden, it will execute _process_array on a small test array to determine the output shape.
Parameters¶
input_shape : tuple Input data shape
Returns¶
tuple Output data shape
Notes¶
The default implementation creates a minimal test array and processes it to determine output shape. For performance-critical code, subclasses should override this method with a direct calculation.
Source code in wandas/processing/base.py
191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 | |
process(data)
¶Execute operation and return result data shape is (channels, samples)
Source code in wandas/processing/base.py
245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 | |
Functions¶
register_operation(operation_class)
¶
Register a new operation type
Source code in wandas/processing/base.py
268 269 270 271 272 273 274 275 276 | |
get_operation(name)
¶
Get operation class by name
Source code in wandas/processing/base.py
279 280 281 282 283 | |
create_operation(name, sampling_rate, **params)
¶
Create operation instance from name and parameters
Source code in wandas/processing/base.py
286 287 288 289 290 291 | |
effects
¶
Attributes¶
logger = logging.getLogger(__name__)
module-attribute
¶
Classes¶
HpssHarmonic
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
HPSS Harmonic operation
Source code in wandas/processing/effects.py
17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 | |
name = 'hpss_harmonic'
class-attribute
instance-attribute
¶ kwargs = kwargs
instance-attribute
¶ __init__(sampling_rate, **kwargs)
¶Initialize HPSS Harmonic
Parameters¶
sampling_rate : float Sampling rate (Hz)
Source code in wandas/processing/effects.py
22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 | |
calculate_output_shape(input_shape)
¶Source code in wandas/processing/effects.py
38 39 | |
get_display_name()
¶Get display name for the operation for use in channel labels.
Source code in wandas/processing/effects.py
41 42 43 | |
HpssPercussive
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
HPSS Percussive operation
Source code in wandas/processing/effects.py
55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 | |
name = 'hpss_percussive'
class-attribute
instance-attribute
¶ kwargs = kwargs
instance-attribute
¶ __init__(sampling_rate, **kwargs)
¶Initialize HPSS Percussive
Parameters¶
sampling_rate : float Sampling rate (Hz)
Source code in wandas/processing/effects.py
60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 | |
calculate_output_shape(input_shape)
¶Source code in wandas/processing/effects.py
76 77 | |
get_display_name()
¶Get display name for the operation for use in channel labels.
Source code in wandas/processing/effects.py
79 80 81 | |
Normalize
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Signal normalization operation using librosa.util.normalize
Source code in wandas/processing/effects.py
93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 | |
name = 'normalize'
class-attribute
instance-attribute
¶ norm = norm
instance-attribute
¶ axis = axis
instance-attribute
¶ threshold = threshold
instance-attribute
¶ fill = fill
instance-attribute
¶ __init__(sampling_rate, norm=np.inf, axis=-1, threshold=None, fill=None)
¶Initialize normalization operation
Parameters¶
sampling_rate : float Sampling rate (Hz) norm : float or np.inf, default=np.inf Norm type. Supported values: - np.inf: Maximum absolute value normalization - -np.inf: Minimum absolute value normalization - 0: Pseudo L0 normalization (divide by number of non-zero elements) - float: Lp norm - None: No normalization axis : int or None, default=-1 Axis along which to normalize. - -1: Normalize along time axis (each channel independently) - None: Global normalization across all axes - int: Normalize along specified axis threshold : float or None, optional Threshold below which values are considered zero. If None, no threshold is applied. fill : bool or None, optional Value to fill when the norm is zero. If None, the zero vector remains zero.
Raises¶
ValueError If norm parameter is invalid or threshold is negative
Source code in wandas/processing/effects.py
98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 | |
calculate_output_shape(input_shape)
¶Calculate output data shape after operation
Parameters¶
input_shape : tuple Input data shape
Returns¶
tuple Output data shape (same as input)
Source code in wandas/processing/effects.py
181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 | |
get_display_name()
¶Get display name for the operation for use in channel labels.
Source code in wandas/processing/effects.py
197 198 199 | |
RemoveDC
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Remove DC component (DC offset) from the signal.
This operation removes the DC component by subtracting the mean value from each channel, centering the signal around zero.
Source code in wandas/processing/effects.py
219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 | |
name = 'remove_dc'
class-attribute
instance-attribute
¶ __init__(sampling_rate)
¶Initialize DC removal operation.
Parameters¶
sampling_rate : float Sampling rate (Hz)
Source code in wandas/processing/effects.py
228 229 230 231 232 233 234 235 236 237 | |
calculate_output_shape(input_shape)
¶Calculate output data shape after operation.
Parameters¶
input_shape : tuple Input data shape
Returns¶
tuple Output data shape (same as input)
Source code in wandas/processing/effects.py
239 240 241 242 243 244 245 246 247 248 249 250 251 252 | |
get_display_name()
¶Get display name for the operation for use in channel labels.
Source code in wandas/processing/effects.py
254 255 256 | |
AddWithSNR
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Addition operation considering SNR
Source code in wandas/processing/effects.py
281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 | |
name = 'add_with_snr'
class-attribute
instance-attribute
¶ other = other
instance-attribute
¶ snr = snr
instance-attribute
¶ __init__(sampling_rate, other, snr=1.0)
¶Initialize addition operation considering SNR
Parameters¶
sampling_rate : float Sampling rate (Hz) other : DaArray Noise signal to add (channel-frame format) snr : float Signal-to-noise ratio (dB)
Source code in wandas/processing/effects.py
286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 | |
calculate_output_shape(input_shape)
¶Calculate output data shape after operation
Parameters¶
input_shape : tuple Input data shape
Returns¶
tuple Output data shape (same as input)
Source code in wandas/processing/effects.py
305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 | |
get_display_name()
¶Get display name for the operation for use in channel labels.
Source code in wandas/processing/effects.py
321 322 323 | |
Fade
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Fade operation using a Tukey (tapered cosine) window.
This operation applies symmetric fade-in and fade-out with the same duration. The Tukey window alpha parameter is computed from the fade duration so that the tapered portion equals the requested fade length at each end.
Source code in wandas/processing/effects.py
344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 | |
name = 'fade'
class-attribute
instance-attribute
¶ fade_ms = float(fade_ms)
instance-attribute
¶ fade_len = int(round(self.fade_ms * float(sampling_rate) / 1000.0))
instance-attribute
¶ __init__(sampling_rate, fade_ms=50)
¶Source code in wandas/processing/effects.py
355 356 357 358 359 | |
validate_params()
¶Source code in wandas/processing/effects.py
361 362 363 | |
calculate_output_shape(input_shape)
¶Source code in wandas/processing/effects.py
365 366 | |
get_display_name()
¶Get display name for the operation for use in channel labels.
Source code in wandas/processing/effects.py
368 369 370 | |
calculate_tukey_alpha(fade_len, n_samples)
staticmethod
¶Calculate Tukey window alpha parameter from fade length.
The alpha parameter determines what fraction of the window is tapered. For symmetric fade-in/fade-out, alpha = 2 * fade_len / n_samples ensures that each side's taper has exactly fade_len samples.
Parameters¶
fade_len : int Desired fade length in samples for each end (in and out). n_samples : int Total number of samples in the signal.
Returns¶
float Alpha parameter for scipy.signal.windows.tukey, clamped to [0, 1].
Examples¶
Fade.calculate_tukey_alpha(fade_len=20, n_samples=200) 0.2 Fade.calculate_tukey_alpha(fade_len=100, n_samples=100) 1.0
Source code in wandas/processing/effects.py
372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 | |
Functions¶
Modules¶
filters
¶
Attributes¶
logger = logging.getLogger(__name__)
module-attribute
¶
Classes¶
HighPassFilter
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
High-pass filter operation
Source code in wandas/processing/filters.py
13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 | |
name = 'highpass_filter'
class-attribute
instance-attribute
¶ a
instance-attribute
¶ b
instance-attribute
¶ cutoff = cutoff
instance-attribute
¶ order = order
instance-attribute
¶ __init__(sampling_rate, cutoff, order=4)
¶Initialize high-pass filter
Parameters¶
sampling_rate : float Sampling rate (Hz) cutoff : float Cutoff frequency (Hz). Must be between 0 and Nyquist frequency (sampling_rate / 2). order : int, optional Filter order, default is 4
Raises¶
ValueError If cutoff frequency is not within valid range (0 < cutoff < Nyquist)
Source code in wandas/processing/filters.py
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 | |
validate_params()
¶Validate parameters
Source code in wandas/processing/filters.py
43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 | |
calculate_output_shape(input_shape)
¶Source code in wandas/processing/filters.py
70 71 | |
get_display_name()
¶Get display name for the operation for use in channel labels.
Source code in wandas/processing/filters.py
73 74 75 | |
LowPassFilter
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Low-pass filter operation
Source code in wandas/processing/filters.py
85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 | |
name = 'lowpass_filter'
class-attribute
instance-attribute
¶ a
instance-attribute
¶ b
instance-attribute
¶ cutoff = cutoff
instance-attribute
¶ order = order
instance-attribute
¶ __init__(sampling_rate, cutoff, order=4)
¶Initialize low-pass filter
Parameters¶
sampling_rate : float Sampling rate (Hz) cutoff : float Cutoff frequency (Hz). Must be between 0 and Nyquist frequency (sampling_rate / 2). order : int, optional Filter order, default is 4
Raises¶
ValueError If cutoff frequency is not within valid range (0 < cutoff < Nyquist)
Source code in wandas/processing/filters.py
92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 | |
validate_params()
¶Validate parameters
Source code in wandas/processing/filters.py
115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 | |
calculate_output_shape(input_shape)
¶Source code in wandas/processing/filters.py
141 142 | |
get_display_name()
¶Get display name for the operation for use in channel labels.
Source code in wandas/processing/filters.py
144 145 146 | |
BandPassFilter
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Band-pass filter operation
Source code in wandas/processing/filters.py
157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 | |
name = 'bandpass_filter'
class-attribute
instance-attribute
¶ a
instance-attribute
¶ b
instance-attribute
¶ low_cutoff = low_cutoff
instance-attribute
¶ high_cutoff = high_cutoff
instance-attribute
¶ order = order
instance-attribute
¶ __init__(sampling_rate, low_cutoff, high_cutoff, order=4)
¶Initialize band-pass filter
Parameters¶
sampling_rate : float Sampling rate (Hz) low_cutoff : float Lower cutoff frequency (Hz). Must be between 0 and Nyquist frequency. high_cutoff : float Higher cutoff frequency (Hz). Must be between 0 and Nyquist frequency and greater than low_cutoff. order : int, optional Filter order, default is 4
Raises¶
ValueError If either cutoff frequency is not within valid range (0 < cutoff < Nyquist), or if low_cutoff >= high_cutoff
Source code in wandas/processing/filters.py
164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 | |
validate_params()
¶Validate parameters
Source code in wandas/processing/filters.py
199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 | |
calculate_output_shape(input_shape)
¶Source code in wandas/processing/filters.py
246 247 | |
get_display_name()
¶Get display name for the operation for use in channel labels.
Source code in wandas/processing/filters.py
249 250 251 | |
AWeighting
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
A-weighting filter operation
Source code in wandas/processing/filters.py
261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 | |
name = 'a_weighting'
class-attribute
instance-attribute
¶ __init__(sampling_rate)
¶Initialize A-weighting filter
Parameters¶
sampling_rate : float Sampling rate (Hz)
Source code in wandas/processing/filters.py
266 267 268 269 270 271 272 273 274 275 | |
calculate_output_shape(input_shape)
¶Source code in wandas/processing/filters.py
277 278 | |
get_display_name()
¶Get display name for the operation for use in channel labels.
Source code in wandas/processing/filters.py
280 281 282 | |
Functions¶
psychoacoustic
¶
Psychoacoustic metrics processing operations.
This module provides psychoacoustic metrics operations for audio signals, including loudness calculation using standardized methods.
Attributes¶
logger = logging.getLogger(__name__)
module-attribute
¶
Classes¶
LoudnessZwtv
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Calculate time-varying loudness using Zwicker method (ISO 532-1:2017).
This operation computes the loudness of non-stationary signals according to the Zwicker method, as specified in ISO 532-1:2017. It uses the MoSQITo library's implementation of the standardized loudness calculation.
The loudness is calculated in sones, a unit of perceived loudness where a doubling of sones corresponds to a doubling of perceived loudness.
Parameters¶
sampling_rate : float Sampling rate in Hz. The signal should be sampled at a rate appropriate for the analysis (typically 44100 Hz or 48000 Hz for audio). field_type : str, default="free" Type of sound field. Options: - 'free': Free field (sound arriving from a specific direction) - 'diffuse': Diffuse field (sound arriving uniformly from all directions)
Attributes¶
name : str Operation name: "loudness_zwtv" field_type : str The sound field type used for calculation
Examples¶
Calculate loudness for a signal:
import wandas as wd signal = wd.read_wav("audio.wav") loudness = signal.loudness_zwtv(field_type="free")
Notes¶
- The output contains time-varying loudness values in sones
- For mono signals, the loudness is calculated directly
- For multi-channel signals, loudness is calculated per channel
- The method follows ISO 532-1:2017 standard for time-varying loudness
- Typical loudness values: 1 sone ≈ 40 phon (loudness level)
References¶
.. [1] ISO 532-1:2017, "Acoustics — Methods for calculating loudness — Part 1: Zwicker method" .. [2] MoSQITo documentation: https://mosqito.readthedocs.io/en/latest/
Source code in wandas/processing/psychoacoustic.py
24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 | |
name = 'loudness_zwtv'
class-attribute
instance-attribute
¶ field_type = field_type
instance-attribute
¶ __init__(sampling_rate, field_type='free')
¶Initialize Loudness calculation operation.
Parameters¶
sampling_rate : float Sampling rate (Hz) field_type : str, default="free" Type of sound field ('free' or 'diffuse')
Source code in wandas/processing/psychoacoustic.py
77 78 79 80 81 82 83 84 85 86 87 88 89 | |
validate_params()
¶Validate parameters.
Raises¶
ValueError If field_type is not 'free' or 'diffuse'
Source code in wandas/processing/psychoacoustic.py
91 92 93 94 95 96 97 98 99 100 101 102 103 | |
get_metadata_updates()
¶Update sampling rate based on MoSQITo's time resolution.
The Zwicker method uses approximately 2ms time steps, which corresponds to 500 Hz sampling rate, independent of the input sampling rate.
Returns¶
dict Metadata updates with new sampling rate
Notes¶
All necessary parameters are provided at initialization. The output sampling rate is always 500 Hz regardless of input.
Source code in wandas/processing/psychoacoustic.py
105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 | |
calculate_output_shape(input_shape)
¶Calculate output data shape after operation.
The loudness calculation produces a time-varying output where the time resolution depends on the algorithm's internal processing. The exact output length is determined dynamically by the loudness_zwtv function.
Parameters¶
input_shape : tuple Input data shape (channels, samples)
Returns¶
tuple Output data shape. For loudness, we return a placeholder shape since the actual length is determined by the algorithm. The shape will be (channels, time_samples) where time_samples depends on the input length and algorithm parameters.
Source code in wandas/processing/psychoacoustic.py
125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 | |
LoudnessZwst
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Calculate steady-state loudness using Zwicker method (ISO 532-1:2017).
This operation computes the loudness of stationary (steady) signals according to the Zwicker method, as specified in ISO 532-1:2017. It uses the MoSQITo library's implementation of the standardized loudness calculation for steady signals.
The loudness is calculated in sones, a unit of perceived loudness where a doubling of sones corresponds to a doubling of perceived loudness.
Parameters¶
sampling_rate : float Sampling rate in Hz. The signal should be sampled at a rate appropriate for the analysis (typically 44100 Hz or 48000 Hz for audio). field_type : str, default="free" Type of sound field. Options: - 'free': Free field (sound arriving from a specific direction) - 'diffuse': Diffuse field (sound arriving uniformly from all directions)
Attributes¶
name : str Operation name: "loudness_zwst" field_type : str The sound field type used for calculation
Examples¶
Calculate steady-state loudness for a signal:
import wandas as wd signal = wd.read_wav("fan_noise.wav") loudness = signal.loudness_zwst(field_type="free") print(f"Steady-state loudness: {loudness.data[0]:.2f} sones")
Notes¶
- The output contains a single loudness value in sones for each channel
- For mono signals, the loudness is calculated directly
- For multi-channel signals, loudness is calculated per channel
- The method follows ISO 532-1:2017 standard for steady-state loudness
- Typical loudness values: 1 sone ≈ 40 phon (loudness level)
- This method is suitable for stationary signals such as fan noise, constant machinery sounds, or other steady sounds
References¶
.. [1] ISO 532-1:2017, "Acoustics — Methods for calculating loudness — Part 1: Zwicker method" .. [2] MoSQITo documentation: https://mosqito.readthedocs.io/en/latest/
Source code in wandas/processing/psychoacoustic.py
223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 | |
name = 'loudness_zwst'
class-attribute
instance-attribute
¶ field_type = field_type
instance-attribute
¶ __init__(sampling_rate, field_type='free')
¶Initialize steady-state loudness calculation operation.
Parameters¶
sampling_rate : float Sampling rate (Hz) field_type : str, default="free" Type of sound field ('free' or 'diffuse')
Source code in wandas/processing/psychoacoustic.py
279 280 281 282 283 284 285 286 287 288 289 290 291 | |
validate_params()
¶Validate parameters.
Raises¶
ValueError If field_type is not 'free' or 'diffuse'
Source code in wandas/processing/psychoacoustic.py
293 294 295 296 297 298 299 300 301 302 303 304 305 | |
get_metadata_updates()
¶Get metadata updates to apply after processing.
For steady-state loudness, the output is a single value per channel, so no sampling rate update is needed (output is scalar, not time-series).
Returns¶
dict Empty dictionary (no metadata updates needed)
Notes¶
Unlike time-varying loudness, steady-state loudness produces a single value, not a time series, so the sampling rate concept doesn't apply.
Source code in wandas/processing/psychoacoustic.py
307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 | |
calculate_output_shape(input_shape)
¶Calculate output data shape after operation.
The steady-state loudness calculation produces a single loudness value per channel.
Parameters¶
input_shape : tuple Input data shape (channels, samples)
Returns¶
tuple Output data shape: (channels, 1) - one loudness value per channel
Source code in wandas/processing/psychoacoustic.py
326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 | |
RoughnessDw
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Calculate time-varying roughness using Daniel and Weber method.
This operation computes the roughness of audio signals according to the Daniel and Weber (1997) method. It uses the MoSQITo library's implementation of the standardized roughness calculation.
Roughness is a psychoacoustic metric that quantifies the perceived harshness or roughness of a sound. The unit is asper, where higher values indicate rougher sounds.
The calculation follows the standard formula: R = 0.25 * sum(R'_i) for i=1 to 47 Bark bands
Parameters¶
sampling_rate : float Sampling rate in Hz. The signal should be sampled at a rate appropriate for the analysis (typically 44100 Hz or 48000 Hz for audio). overlap : float, default=0.5 Overlapping coefficient for the analysis windows (0.0 to 1.0). The analysis uses 200ms windows: - overlap=0.5: 100ms hop size → ~10 Hz output sampling rate - overlap=0.0: 200ms hop size → ~5 Hz output sampling rate
Attributes¶
name : str Operation name: "roughness_dw" overlap : float The overlapping coefficient used for calculation
Examples¶
Calculate roughness for a signal:
import wandas as wd signal = wd.read_wav("motor_noise.wav") roughness = signal.roughness_dw(overlap=0.5) print(f"Mean roughness: {roughness.data.mean():.2f} asper")
Notes¶
- The output contains time-varying roughness values in asper
- For mono signals, the roughness is calculated directly
- For multi-channel signals, roughness is calculated per channel
- The method follows Daniel & Weber (1997) standard
- Typical roughness values: 0-2 asper for most sounds
- Higher overlap values provide better time resolution but increase computational cost
References¶
.. [1] Daniel, P., & Weber, R. (1997). "Psychoacoustical roughness: Implementation of an optimized model." Acustica, 83, 113-123. .. [2] MoSQITo documentation: https://mosqito.readthedocs.io/en/latest/
Source code in wandas/processing/psychoacoustic.py
414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 | |
name = 'roughness_dw'
class-attribute
instance-attribute
¶ overlap = overlap
instance-attribute
¶ __init__(sampling_rate, overlap=0.5)
¶Initialize Roughness calculation operation.
Parameters¶
sampling_rate : float Sampling rate (Hz) overlap : float, default=0.5 Overlapping coefficient (0.0 to 1.0)
Source code in wandas/processing/psychoacoustic.py
475 476 477 478 479 480 481 482 483 484 485 486 487 | |
validate_params()
¶Validate parameters.
Raises¶
ValueError If overlap is not in [0.0, 1.0]
Source code in wandas/processing/psychoacoustic.py
489 490 491 492 493 494 495 496 497 498 499 | |
get_metadata_updates()
¶Update sampling rate based on overlap and window size.
The Daniel & Weber method uses 200ms windows. The output sampling rate depends on the overlap: - overlap=0.0: hop=200ms → fs=5 Hz - overlap=0.5: hop=100ms → fs=10 Hz - overlap=0.75: hop=50ms → fs=20 Hz
Returns¶
dict Metadata updates with new sampling rate
Notes¶
The output sampling rate is approximately 1 / (0.2 * (1 - overlap)) Hz.
Source code in wandas/processing/psychoacoustic.py
501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 | |
calculate_output_shape(input_shape)
¶Calculate output data shape after operation.
The roughness calculation produces a time-varying output where the number of time points depends on the signal length and overlap.
Parameters¶
input_shape : tuple Input data shape (channels, samples)
Returns¶
tuple Output data shape (channels, time_samples)
Source code in wandas/processing/psychoacoustic.py
525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 | |
RoughnessDwSpec
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Specific roughness (R_spec) operation.
Computes per-Bark-band specific roughness over time using MoSQITo's
roughness_dw implementation. Output is band-by-time.
The bark_axis is retrieved dynamically from MoSQITo during initialization to ensure consistency with MoSQITo's implementation. Results are cached based on sampling_rate and overlap to avoid redundant computations.
Source code in wandas/processing/psychoacoustic.py
630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 | |
name = 'roughness_dw_spec'
class-attribute
instance-attribute
¶ overlap = overlap
instance-attribute
¶ bark_axis
property
¶ __init__(sampling_rate, overlap=0.5)
¶Source code in wandas/processing/psychoacoustic.py
645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 | |
validate_params()
¶Source code in wandas/processing/psychoacoustic.py
698 699 700 | |
get_metadata_updates()
¶Source code in wandas/processing/psychoacoustic.py
702 703 704 705 706 707 | |
calculate_output_shape(input_shape)
¶Source code in wandas/processing/psychoacoustic.py
709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 | |
SharpnessDin
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Calculate time-varying sharpness using DIN 45692 method.
This operation computes the sharpness of audio signals according to the DIN 45692 standard. It uses the MoSQITo library's implementation of the standardized sharpness calculation.
Sharpness quantifies the perceived sharpness of a sound, with units in acum (acum = 1 when the sound has the same sharpness as a 2 kHz narrow-band noise with a level of 60 dB).
Parameters¶
sampling_rate : float Sampling rate in Hz. The signal should be sampled at a rate appropriate for the analysis (typically 44100 Hz or 48000 Hz for audio). weighting : str, default="din" Weighting function used for the sharpness computation. Options: - 'din': DIN 45692 method - 'aures': Aures method - 'bismarck': Bismarck method - 'fastl': Fastl method field_type : str, default="free" Type of sound field. Options: - 'free': Free field (sound arriving from a specific direction) - 'diffuse': Diffuse field (sound arriving uniformly from all directions)
Attributes¶
name : str Operation name: "sharpness_din" weighting : str The weighting function used for sharpness calculation field_type : str The sound field type used for calculation
Examples¶
Calculate sharpness for a signal:
import wandas as wd signal = wd.read_wav("sharp_sound.wav") sharpness = signal.sharpness_din(weighting="din", field_type="free") print(f"Mean sharpness: {sharpness.data.mean():.2f} acum")
Notes¶
- The output contains time-varying sharpness values in acum
- For mono signals, the sharpness is calculated directly
- For multi-channel signals, sharpness is calculated per channel
- The method follows DIN 45692 standard
- Typical sharpness values: 0-5 acum for most sounds
References¶
.. [1] DIN 45692:2009, "Measurement technique for the simulation of the auditory sensation of sharpness" .. [2] MoSQITo documentation: https://mosqito.readthedocs.io/en/latest/
Source code in wandas/processing/psychoacoustic.py
775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 | |
name = 'sharpness_din'
class-attribute
instance-attribute
¶ weighting = weighting
instance-attribute
¶ field_type = field_type
instance-attribute
¶ __init__(sampling_rate, weighting='din', field_type='free')
¶Initialize Sharpness calculation operation.
Parameters¶
sampling_rate : float Sampling rate (Hz) weighting : str, default="din" Weighting function ('din', 'aures', 'bismarck', 'fastl') field_type : str, default="free" Type of sound field ('free' or 'diffuse')
Source code in wandas/processing/psychoacoustic.py
838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 | |
validate_params()
¶Validate parameters.
Raises¶
ValueError If weighting or field_type is invalid.
Source code in wandas/processing/psychoacoustic.py
857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 | |
get_metadata_updates()
¶Update sampling rate based on DIN 45692 time resolution.
The DIN 45692 method uses approximately 2ms time steps, which corresponds to 500 Hz sampling rate, independent of the input sampling rate.
Returns¶
dict Metadata updates with new sampling rate
Notes¶
All necessary parameters are provided at initialization. The output sampling rate is always 500 Hz regardless of input.
Source code in wandas/processing/psychoacoustic.py
881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 | |
calculate_output_shape(input_shape)
¶Calculate output data shape after operation.
The sharpness calculation produces a time-varying output where the time resolution depends on the algorithm's internal processing. The exact output length is determined dynamically by the sharpness_din_tv function.
Parameters¶
input_shape : tuple Input data shape (channels, samples)
Returns¶
tuple Output data shape. For sharpness, we return a placeholder shape since the actual length is determined by the algorithm. The shape will be (channels, time_samples) where time_samples depends on the input length and algorithm parameters.
Source code in wandas/processing/psychoacoustic.py
901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 | |
SharpnessDinSt
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Calculate steady-state sharpness using DIN 45692 method.
This operation computes the sharpness of stationary (steady) audio signals according to the DIN 45692 standard. It uses the MoSQITo library's implementation of the standardized sharpness calculation for steady signals.
Sharpness quantifies the perceived sharpness of a sound, with units in acum (acum = 1 when the sound has the same sharpness as a 2 kHz narrow-band noise with a level of 60 dB).
Parameters¶
sampling_rate : float Sampling rate in Hz. The signal should be sampled at a rate appropriate for the analysis (typically 44100 Hz or 48000 Hz for audio). weighting : str, default="din" Weighting function used for the sharpness computation. Options: - 'din': DIN 45692 method - 'aures': Aures method - 'bismarck': Bismarck method - 'fastl': Fastl method field_type : str, default="free" Type of sound field. Options: - 'free': Free field (sound arriving from a specific direction) - 'diffuse': Diffuse field (sound arriving uniformly from all directions)
Attributes¶
name : str Operation name: "sharpness_din_st" weighting : str The weighting function used for sharpness calculation field_type : str The sound field type used for calculation
Examples¶
Calculate steady-state sharpness for a signal:
import wandas as wd signal = wd.read_wav("constant_tone.wav") sharpness = signal.sharpness_din_st(weighting="din", field_type="free") print(f"Steady-state sharpness: {sharpness.data[0]:.2f} acum")
Notes¶
- The output contains a single sharpness value in acum for each channel
- For mono signals, the sharpness is calculated directly
- For multi-channel signals, sharpness is calculated per channel
- The method follows DIN 45692 standard for steady-state sharpness
- Typical sharpness values: 0-5 acum for most sounds
- This method is suitable for stationary signals such as constant tones, steady noise, or other unchanging sounds
References¶
.. [1] DIN 45692:2009, "Measurement technique for the simulation of the auditory sensation of sharpness" .. [2] MoSQITo documentation: https://mosqito.readthedocs.io/en/latest/
Source code in wandas/processing/psychoacoustic.py
1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 | |
name = 'sharpness_din_st'
class-attribute
instance-attribute
¶ weighting = weighting
instance-attribute
¶ field_type = field_type
instance-attribute
¶ __init__(sampling_rate, weighting='din', field_type='free')
¶Initialize steady-state sharpness calculation operation.
Parameters¶
sampling_rate : float Sampling rate (Hz) weighting : str, default="din" Weighting function ('din', 'aures', 'bismarck', 'fastl') field_type : str, default="free" Type of sound field ('free' or 'diffuse')
Source code in wandas/processing/psychoacoustic.py
1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 | |
validate_params()
¶Validate parameters.
Raises¶
ValueError If weighting or field_type is invalid.
Source code in wandas/processing/psychoacoustic.py
1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 | |
get_metadata_updates()
¶Get metadata updates to apply after processing.
For steady-state sharpness, the output is a single value per channel, so no sampling rate update is needed (output is scalar, not time-series).
Returns¶
dict Empty dictionary (no metadata updates needed)
Notes¶
Unlike time-varying sharpness, steady-state sharpness produces a single value, not a time series, so the sampling rate concept doesn't apply.
Source code in wandas/processing/psychoacoustic.py
1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 | |
calculate_output_shape(input_shape)
¶Calculate output data shape after operation.
The steady-state sharpness calculation produces a single sharpness value per channel.
Parameters¶
input_shape : tuple Input data shape (channels, samples)
Returns¶
tuple Output data shape: (channels, 1) - one sharpness value per channel
Source code in wandas/processing/psychoacoustic.py
1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 | |
Functions¶
spectral
¶
Attributes¶
logger = logging.getLogger(__name__)
module-attribute
¶
Classes¶
FFT
¶
Bases: AudioOperation[NDArrayReal, NDArrayComplex]
FFT (Fast Fourier Transform) operation
Source code in wandas/processing/spectral.py
116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 | |
name = 'fft'
class-attribute
instance-attribute
¶ n_fft = n_fft
instance-attribute
¶ window = window
instance-attribute
¶ __init__(sampling_rate, n_fft=None, window='hann')
¶Initialize FFT operation
Parameters¶
sampling_rate : float Sampling rate (Hz) n_fft : int, optional FFT size, default is None (determined by input size) window : str, optional Window function type, default is 'hann'
Raises¶
ValueError If n_fft is not a positive integer
Source code in wandas/processing/spectral.py
123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 | |
calculate_output_shape(input_shape)
¶操作後の出力データの形状を計算します
Parameters¶
input_shape : tuple 入力データの形状 (channels, samples)
Returns¶
tuple 出力データの形状 (channels, freqs)
Source code in wandas/processing/spectral.py
158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 | |
get_display_name()
¶Get display name for the operation for use in channel labels.
Source code in wandas/processing/spectral.py
175 176 177 | |
IFFT
¶
Bases: AudioOperation[NDArrayComplex, NDArrayReal]
IFFT (Inverse Fast Fourier Transform) operation
Source code in wandas/processing/spectral.py
197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 | |
name = 'ifft'
class-attribute
instance-attribute
¶ n_fft = n_fft
instance-attribute
¶ window = window
instance-attribute
¶ __init__(sampling_rate, n_fft=None, window='hann')
¶Initialize IFFT operation
Parameters¶
sampling_rate : float Sampling rate (Hz) n_fft : Optional[int], optional IFFT size, default is None (determined based on input size) window : str, optional Window function type, default is 'hann'
Source code in wandas/processing/spectral.py
204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 | |
calculate_output_shape(input_shape)
¶Calculate output data shape after operation
Parameters¶
input_shape : tuple Input data shape (channels, freqs)
Returns¶
tuple Output data shape (channels, samples)
Source code in wandas/processing/spectral.py
223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 | |
get_display_name()
¶Get display name for the operation for use in channel labels.
Source code in wandas/processing/spectral.py
240 241 242 | |
STFT
¶
Bases: AudioOperation[NDArrayReal, NDArrayComplex]
Short-Time Fourier Transform operation
Source code in wandas/processing/spectral.py
268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 | |
name = 'stft'
class-attribute
instance-attribute
¶ n_fft = n_fft
instance-attribute
¶ win_length = actual_win_length
instance-attribute
¶ hop_length = actual_hop_length
instance-attribute
¶ noverlap = self.win_length - self.hop_length if hop_length is not None else None
instance-attribute
¶ window = window
instance-attribute
¶ SFT = ShortTimeFFT(win=(get_window(window, self.win_length)), hop=(self.hop_length), fs=sampling_rate, mfft=(self.n_fft), scale_to='magnitude')
instance-attribute
¶ __init__(sampling_rate, n_fft=2048, hop_length=None, win_length=None, window='hann')
¶Initialize STFT operation
Parameters¶
sampling_rate : float Sampling rate (Hz) n_fft : int FFT size, default is 2048 hop_length : int, optional Number of samples between frames. Default is win_length // 4 win_length : int, optional Window length. Default is n_fft window : str Window type, default is 'hann'
Raises¶
ValueError If n_fft is not positive, win_length > n_fft, or hop_length is invalid
Source code in wandas/processing/spectral.py
273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 | |
calculate_output_shape(input_shape)
¶Calculate output data shape after operation
Parameters¶
input_shape : tuple Input data shape
Returns¶
tuple Output data shape
Source code in wandas/processing/spectral.py
330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 | |
get_display_name()
¶Get display name for the operation for use in channel labels.
Source code in wandas/processing/spectral.py
349 350 351 | |
ISTFT
¶
Bases: AudioOperation[NDArrayComplex, NDArrayReal]
Inverse Short-Time Fourier Transform operation
Source code in wandas/processing/spectral.py
368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 | |
name = 'istft'
class-attribute
instance-attribute
¶ n_fft = n_fft
instance-attribute
¶ win_length = actual_win_length
instance-attribute
¶ hop_length = actual_hop_length
instance-attribute
¶ window = window
instance-attribute
¶ length = length
instance-attribute
¶ SFT = ShortTimeFFT(win=(get_window(window, self.win_length)), hop=(self.hop_length), fs=sampling_rate, mfft=(self.n_fft), scale_to='magnitude')
instance-attribute
¶ __init__(sampling_rate, n_fft=2048, hop_length=None, win_length=None, window='hann', length=None)
¶Initialize ISTFT operation
Parameters¶
sampling_rate : float Sampling rate (Hz) n_fft : int FFT size, default is 2048 hop_length : int, optional Number of samples between frames. Default is win_length // 4 win_length : int, optional Window length. Default is n_fft window : str Window type, default is 'hann' length : int, optional Length of output signal. Default is None (determined from input)
Raises¶
ValueError If n_fft is not positive, win_length > n_fft, or hop_length is invalid
Source code in wandas/processing/spectral.py
373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 | |
calculate_output_shape(input_shape)
¶Calculate output data shape after ISTFT operation.
Uses the SciPy ShortTimeFFT calculation formula to compute the expected output length based on the input spectrogram dimensions and output range parameters (k0, k1).
Parameters¶
input_shape : tuple Input spectrogram shape (channels, n_freqs, n_frames) where n_freqs = n_fft // 2 + 1 and n_frames is the number of time frames.
Returns¶
tuple Output shape (channels, output_samples) where output_samples is the reconstructed signal length determined by the output range [k0, k1).
Notes¶
The calculation follows SciPy's ShortTimeFFT.istft() implementation. When k1 is None (default), the maximum reconstructible signal length is computed as:
.. math::
q_{max} = n_{frames} + p_{min}
k_{max} = (q_{max} - 1) \cdot hop + m_{num} - m_{num\_mid}
The output length is then:
.. math::
output\_samples = k_1 - k_0
where k0 defaults to 0 and k1 defaults to k_max.
Parameters that affect the calculation: - n_frames: number of time frames in the STFT - p_min: minimum frame index (ShortTimeFFT property) - hop: hop length (samples between frames) - m_num: window length - m_num_mid: window midpoint position - self.length: optional length override (if set, limits output)
References¶
- SciPy ShortTimeFFT.istft: https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.ShortTimeFFT.istft.html
- SciPy Source: https://github.com/scipy/scipy/blob/main/scipy/signal/_short_time_fft.py
Source code in wandas/processing/spectral.py
434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 | |
get_display_name()
¶Get display name for the operation for use in channel labels.
Source code in wandas/processing/spectral.py
509 510 511 | |
Welch
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Welch
Source code in wandas/processing/spectral.py
541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 | |
name = 'welch'
class-attribute
instance-attribute
¶ n_fft = n_fft
instance-attribute
¶ win_length = actual_win_length
instance-attribute
¶ hop_length = actual_hop_length
instance-attribute
¶ noverlap = self.win_length - self.hop_length if hop_length is not None else None
instance-attribute
¶ window = window
instance-attribute
¶ average = average
instance-attribute
¶ detrend = detrend
instance-attribute
¶ __init__(sampling_rate, n_fft=2048, hop_length=None, win_length=None, window='hann', average='mean', detrend='constant')
¶Initialize Welch operation
Parameters¶
sampling_rate : float Sampling rate (Hz) n_fft : int, optional FFT size, default is 2048 hop_length : int, optional Number of samples between frames. Default is win_length // 4 win_length : int, optional Window length. Default is n_fft window : str, optional Window function type, default is 'hann' average : str, optional Averaging method, default is 'mean' detrend : str, optional Detrend method, default is 'constant'
Raises¶
ValueError If n_fft, win_length, or hop_length are invalid
Source code in wandas/processing/spectral.py
552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 | |
calculate_output_shape(input_shape)
¶Calculate output data shape after operation
Parameters¶
input_shape : tuple Input data shape (channels, samples)
Returns¶
tuple Output data shape (channels, freqs)
Source code in wandas/processing/spectral.py
611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 | |
get_display_name()
¶Get display name for the operation for use in channel labels.
Source code in wandas/processing/spectral.py
628 629 630 | |
NOctSpectrum
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
N-octave spectrum operation
Source code in wandas/processing/spectral.py
655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 | |
name = 'noct_spectrum'
class-attribute
instance-attribute
¶ fmin = fmin
instance-attribute
¶ fmax = fmax
instance-attribute
¶ n = n
instance-attribute
¶ G = G
instance-attribute
¶ fr = fr
instance-attribute
¶ __init__(sampling_rate, fmin, fmax, n=3, G=10, fr=1000)
¶Initialize N-octave spectrum
Parameters¶
sampling_rate : float Sampling rate (Hz) fmin : float Minimum frequency (Hz) fmax : float Maximum frequency (Hz) n : int, optional Number of octave divisions, default is 3 G : int, optional Reference level, default is 10 fr : int, optional Reference frequency, default is 1000
Source code in wandas/processing/spectral.py
660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 | |
calculate_output_shape(input_shape)
¶Calculate output data shape after operation
Parameters¶
input_shape : tuple Input data shape
Returns¶
tuple Output data shape
Source code in wandas/processing/spectral.py
694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 | |
get_display_name()
¶Get display name for the operation for use in channel labels.
Source code in wandas/processing/spectral.py
714 715 716 | |
NOctSynthesis
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Octave synthesis operation
Source code in wandas/processing/spectral.py
739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 | |
name = 'noct_synthesis'
class-attribute
instance-attribute
¶ fmin = fmin
instance-attribute
¶ fmax = fmax
instance-attribute
¶ n = n
instance-attribute
¶ G = G
instance-attribute
¶ fr = fr
instance-attribute
¶ __init__(sampling_rate, fmin, fmax, n=3, G=10, fr=1000)
¶Initialize octave synthesis
Parameters¶
sampling_rate : float Sampling rate (Hz) fmin : float Minimum frequency (Hz) fmax : float Maximum frequency (Hz) n : int, optional Number of octave divisions, default is 3 G : int, optional Reference level, default is 10 fr : int, optional Reference frequency, default is 1000
Source code in wandas/processing/spectral.py
744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 | |
calculate_output_shape(input_shape)
¶Calculate output data shape after operation
Parameters¶
input_shape : tuple Input data shape
Returns¶
tuple Output data shape
Source code in wandas/processing/spectral.py
779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 | |
get_display_name()
¶Get display name for the operation for use in channel labels.
Source code in wandas/processing/spectral.py
799 800 801 | |
Coherence
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Coherence estimation operation
Source code in wandas/processing/spectral.py
829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 | |
name = 'coherence'
class-attribute
instance-attribute
¶ n_fft = n_fft
instance-attribute
¶ win_length = actual_win_length
instance-attribute
¶ hop_length = actual_hop_length
instance-attribute
¶ window = window
instance-attribute
¶ detrend = detrend
instance-attribute
¶ __init__(sampling_rate, n_fft=2048, hop_length=None, win_length=None, window='hann', detrend='constant')
¶Initialize coherence estimation operation
Parameters¶
sampling_rate : float Sampling rate (Hz) n_fft : int FFT size, default is 2048 hop_length : int, optional Number of samples between frames. Default is win_length // 4 win_length : int, optional Window length. Default is n_fft window : str Window function, default is 'hann' detrend : str Type of detrend, default is 'constant'
Raises¶
ValueError If n_fft is not positive, win_length > n_fft, or hop_length is invalid
Source code in wandas/processing/spectral.py
834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 | |
calculate_output_shape(input_shape)
¶Calculate output data shape after operation
Parameters¶
input_shape : tuple Input data shape (channels, samples)
Returns¶
tuple Output data shape (channels * channels, freqs)
Source code in wandas/processing/spectral.py
885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 | |
get_display_name()
¶Get display name for the operation for use in channel labels.
Source code in wandas/processing/spectral.py
903 904 905 | |
CSD
¶
Bases: AudioOperation[NDArrayReal, NDArrayComplex]
Cross-spectral density estimation operation
Source code in wandas/processing/spectral.py
930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 | |
name = 'csd'
class-attribute
instance-attribute
¶ n_fft = n_fft
instance-attribute
¶ win_length = actual_win_length
instance-attribute
¶ hop_length = actual_hop_length
instance-attribute
¶ window = window
instance-attribute
¶ detrend = detrend
instance-attribute
¶ scaling = scaling
instance-attribute
¶ average = average
instance-attribute
¶ __init__(sampling_rate, n_fft=2048, hop_length=None, win_length=None, window='hann', detrend='constant', scaling='spectrum', average='mean')
¶Initialize cross-spectral density estimation operation
Parameters¶
sampling_rate : float Sampling rate (Hz) n_fft : int FFT size, default is 2048 hop_length : int, optional Number of samples between frames. Default is win_length // 4 win_length : int, optional Window length. Default is n_fft window : str Window function, default is 'hann' detrend : str Type of detrend, default is 'constant' scaling : str Type of scaling, default is 'spectrum' average : str Method of averaging, default is 'mean'
Raises¶
ValueError If n_fft is not positive, win_length > n_fft, or hop_length is invalid
Source code in wandas/processing/spectral.py
935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 | |
calculate_output_shape(input_shape)
¶Calculate output data shape after operation
Parameters¶
input_shape : tuple Input data shape (channels, samples)
Returns¶
tuple Output data shape (channels * channels, freqs)
Source code in wandas/processing/spectral.py
996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 | |
get_display_name()
¶Get display name for the operation for use in channel labels.
Source code in wandas/processing/spectral.py
1014 1015 1016 | |
TransferFunction
¶
Bases: AudioOperation[NDArrayReal, NDArrayComplex]
Transfer function estimation operation
Source code in wandas/processing/spectral.py
1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 | |
name = 'transfer_function'
class-attribute
instance-attribute
¶ n_fft = n_fft
instance-attribute
¶ win_length = actual_win_length
instance-attribute
¶ hop_length = actual_hop_length
instance-attribute
¶ window = window
instance-attribute
¶ detrend = detrend
instance-attribute
¶ scaling = scaling
instance-attribute
¶ average = average
instance-attribute
¶ __init__(sampling_rate, n_fft=2048, hop_length=None, win_length=None, window='hann', detrend='constant', scaling='spectrum', average='mean')
¶Initialize transfer function estimation operation
Parameters¶
sampling_rate : float Sampling rate (Hz) n_fft : int FFT size, default is 2048 hop_length : int, optional Number of samples between frames. Default is win_length // 4 win_length : int, optional Window length. Default is n_fft window : str Window function, default is 'hann' detrend : str Type of detrend, default is 'constant' scaling : str Type of scaling, default is 'spectrum' average : str Method of averaging, default is 'mean'
Raises¶
ValueError If n_fft is not positive, win_length > n_fft, or hop_length is invalid
Source code in wandas/processing/spectral.py
1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 | |
calculate_output_shape(input_shape)
¶Calculate output data shape after operation
Parameters¶
input_shape : tuple Input data shape (channels, samples)
Returns¶
tuple Output data shape (channels * channels, freqs)
Source code in wandas/processing/spectral.py
1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 | |
get_display_name()
¶Get display name for the operation for use in channel labels.
Source code in wandas/processing/spectral.py
1130 1131 1132 | |
Functions¶
stats
¶
Attributes¶
logger = logging.getLogger(__name__)
module-attribute
¶
Classes¶
ABS
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Absolute value operation
Source code in wandas/processing/stats.py
12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 | |
name = 'abs'
class-attribute
instance-attribute
¶ __init__(sampling_rate)
¶Initialize absolute value operation
Parameters¶
sampling_rate : float Sampling rate (Hz)
Source code in wandas/processing/stats.py
17 18 19 20 21 22 23 24 25 26 | |
get_display_name()
¶Get display name for the operation for use in channel labels.
Source code in wandas/processing/stats.py
28 29 30 | |
process(data)
¶Source code in wandas/processing/stats.py
32 33 34 | |
Power
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Power operation
Source code in wandas/processing/stats.py
37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 | |
name = 'power'
class-attribute
instance-attribute
¶ exp = exponent
instance-attribute
¶ __init__(sampling_rate, exponent)
¶Initialize power operation
Parameters¶
sampling_rate : float Sampling rate (Hz) exponent : float Power exponent
Source code in wandas/processing/stats.py
42 43 44 45 46 47 48 49 50 51 52 53 54 | |
get_display_name()
¶Get display name for the operation for use in channel labels.
Source code in wandas/processing/stats.py
56 57 58 | |
process(data)
¶Source code in wandas/processing/stats.py
60 61 62 | |
Sum
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Sum calculation
Source code in wandas/processing/stats.py
65 66 67 68 69 70 71 72 73 74 75 76 | |
name = 'sum'
class-attribute
instance-attribute
¶ get_display_name()
¶Get display name for the operation for use in channel labels.
Source code in wandas/processing/stats.py
70 71 72 | |
process(data)
¶Source code in wandas/processing/stats.py
74 75 76 | |
Mean
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Mean calculation
Source code in wandas/processing/stats.py
79 80 81 82 83 84 85 86 87 88 89 90 | |
name = 'mean'
class-attribute
instance-attribute
¶ get_display_name()
¶Get display name for the operation for use in channel labels.
Source code in wandas/processing/stats.py
84 85 86 | |
process(data)
¶Source code in wandas/processing/stats.py
88 89 90 | |
ChannelDifference
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Channel difference calculation operation
Source code in wandas/processing/stats.py
93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 | |
name = 'channel_difference'
class-attribute
instance-attribute
¶ other_channel = other_channel
instance-attribute
¶ __init__(sampling_rate, other_channel=0)
¶Initialize channel difference calculation
Parameters¶
sampling_rate : float Sampling rate (Hz) other_channel : int Channel to calculate difference with, default is 0
Source code in wandas/processing/stats.py
99 100 101 102 103 104 105 106 107 108 109 110 111 | |
get_display_name()
¶Get display name for the operation for use in channel labels.
Source code in wandas/processing/stats.py
113 114 115 | |
process(data)
¶Source code in wandas/processing/stats.py
117 118 119 120 | |
Functions¶
temporal
¶
Attributes¶
logger = logging.getLogger(__name__)
module-attribute
¶
Classes¶
ReSampling
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Resampling operation
Source code in wandas/processing/temporal.py
15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 | |
name = 'resampling'
class-attribute
instance-attribute
¶ target_sr = target_sr
instance-attribute
¶ __init__(sampling_rate, target_sr)
¶Initialize resampling operation
Parameters¶
sampling_rate : float Sampling rate (Hz) target_sampling_rate : float Target sampling rate (Hz)
Raises¶
ValueError If sampling_rate or target_sr is not positive
Source code in wandas/processing/temporal.py
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 | |
get_metadata_updates()
¶Update sampling rate to target sampling rate.
Returns¶
dict Metadata updates with new sampling rate
Notes¶
Resampling always produces output at target_sr, regardless of input sampling rate. All necessary parameters are provided at initialization.
Source code in wandas/processing/temporal.py
41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 | |
calculate_output_shape(input_shape)
¶Calculate output data shape after operation
Parameters¶
input_shape : tuple Input data shape
Returns¶
tuple Output data shape
Source code in wandas/processing/temporal.py
57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 | |
get_display_name()
¶Get display name for the operation for use in channel labels.
Source code in wandas/processing/temporal.py
76 77 78 | |
Trim
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
Trimming operation
Source code in wandas/processing/temporal.py
90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 | |
name = 'trim'
class-attribute
instance-attribute
¶ start = start
instance-attribute
¶ end = end
instance-attribute
¶ start_sample = int(start * sampling_rate)
instance-attribute
¶ end_sample = int(end * sampling_rate)
instance-attribute
¶ __init__(sampling_rate, start, end)
¶Initialize trimming operation
Parameters¶
sampling_rate : float Sampling rate (Hz) start : float Start time for trimming (seconds) end : float End time for trimming (seconds)
Source code in wandas/processing/temporal.py
95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 | |
calculate_output_shape(input_shape)
¶Calculate output data shape after operation
Parameters¶
input_shape : tuple Input data shape
Returns¶
tuple Output data shape
Source code in wandas/processing/temporal.py
122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 | |
get_display_name()
¶Get display name for the operation for use in channel labels.
Source code in wandas/processing/temporal.py
142 143 144 | |
FixLength
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
信号の長さを指定された長さに調整する操作
Source code in wandas/processing/temporal.py
155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 | |
name = 'fix_length'
class-attribute
instance-attribute
¶ target_length = length
instance-attribute
¶ __init__(sampling_rate, length=None, duration=None)
¶Initialize fix length operation
Parameters¶
sampling_rate : float Sampling rate (Hz) length : Optional[int] Target length for fixing duration : Optional[float] Target length for fixing
Source code in wandas/processing/temporal.py
160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 | |
calculate_output_shape(input_shape)
¶Calculate output data shape after operation
Parameters¶
input_shape : tuple Input data shape
Returns¶
tuple Output data shape
Source code in wandas/processing/temporal.py
187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 | |
get_display_name()
¶Get display name for the operation for use in channel labels.
Source code in wandas/processing/temporal.py
203 204 205 | |
RmsTrend
¶
Bases: AudioOperation[NDArrayReal, NDArrayReal]
RMS calculation
Source code in wandas/processing/temporal.py
220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 | |
name = 'rms_trend'
class-attribute
instance-attribute
¶ frame_length = frame_length
instance-attribute
¶ hop_length = hop_length
instance-attribute
¶ dB = dB
instance-attribute
¶ Aw = Aw
instance-attribute
¶ ref = np.array(ref if isinstance(ref, list) else [ref])
instance-attribute
¶ __init__(sampling_rate, frame_length=2048, hop_length=512, ref=1.0, dB=False, Aw=False)
¶Initialize RMS calculation
Parameters¶
sampling_rate : float Sampling rate (Hz) frame_length : int Frame length, default is 2048 hop_length : int Hop length, default is 512 ref : Union[list[float], float] Reference value(s) for dB calculation dB : bool Whether to convert to decibels Aw : bool Whether to apply A-weighting before RMS calculation
Source code in wandas/processing/temporal.py
228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 | |
get_metadata_updates()
¶Update sampling rate based on hop length.
Returns¶
dict Metadata updates with new sampling rate based on hop length
Notes¶
The output sampling rate is determined by downsampling the input by hop_length. All necessary parameters are provided at initialization.
Source code in wandas/processing/temporal.py
269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 | |
calculate_output_shape(input_shape)
¶Calculate output data shape after operation
Parameters¶
input_shape : tuple Input data shape (channels, samples)
Returns¶
tuple Output data shape (channels, frames)
Source code in wandas/processing/temporal.py
286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 | |
get_display_name()
¶Get display name for the operation for use in channel labels.
Source code in wandas/processing/temporal.py
307 308 309 | |
Functions¶
入出力モジュール¶
入出力モジュールはファイルの読み書き機能を提供します。
wandas.io
¶
Attributes¶
__all__ = ['read_wav', 'write_wav', 'load', 'save']
module-attribute
¶
Functions¶
read_wav(filename, labels=None)
¶
Read a WAV file and create a ChannelFrame object.
Parameters¶
filename : str Path to the WAV file or URL to the WAV file. labels : list of str, optional Labels for each channel.
Returns¶
ChannelFrame ChannelFrame object containing the audio data.
Source code in wandas/io/wav_io.py
18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 | |
write_wav(filename, target, format=None)
¶
Write a ChannelFrame object to a WAV file.
Parameters¶
filename : str Path to the WAV file. target : ChannelFrame ChannelFrame object containing the data to write. format : str, optional File format. If None, determined from file extension.
Raises¶
ValueError If target is not a ChannelFrame object.
Source code in wandas/io/wav_io.py
70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 | |
load(path, *, format='hdf5')
¶
Load a ChannelFrame object from a WDF (Wandas Data File) file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | Path
|
Path to the WDF file to load. |
required |
format
|
str
|
Format of the file. Currently only "hdf5" is supported. |
'hdf5'
|
Returns:
| Type | Description |
|---|---|
ChannelFrame
|
A new ChannelFrame object with data and metadata loaded from the file. |
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
If the file doesn't exist. |
NotImplementedError
|
If format is not "hdf5". |
ValueError
|
If the file format is invalid or incompatible. |
Example
cf = ChannelFrame.load("audio_data.wdf")
Source code in wandas/io/wdf_io.py
144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 | |
save(frame, path, *, format='hdf5', compress='gzip', overwrite=False, dtype=None)
¶
Save a frame to a file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
frame
|
BaseFrame[Any]
|
The frame to save. |
required |
path
|
str | Path
|
Path to save the file. '.wdf' extension will be added if not present. |
required |
format
|
str
|
Format to use (currently only 'hdf5' is supported) |
'hdf5'
|
compress
|
str | None
|
Compression method ('gzip' by default, None for no compression) |
'gzip'
|
overwrite
|
bool
|
Whether to overwrite existing file |
False
|
dtype
|
str | dtype[Any] | None
|
Optional data type conversion before saving (e.g. 'float32') |
None
|
Raises:
| Type | Description |
|---|---|
FileExistsError
|
If the file exists and overwrite=False. |
NotImplementedError
|
For unsupported formats. |
Source code in wandas/io/wdf_io.py
31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 | |
Modules¶
readers
¶
Attributes¶
logger = logging.getLogger(__name__)
module-attribute
¶
Classes¶
CSVFileInfoParams
¶
Bases: TypedDict
Type definition for CSV file reader parameters in get_file_info.
Parameters¶
delimiter : str Delimiter character. Default is ",". header : Optional[int] Row number to use as header. Default is 0 (first row). Set to None if no header. time_column : Union[int, str] Index or name of the time column. Default is 0.
Source code in wandas/io/readers.py
14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 | |
CSVGetDataParams
¶
Bases: TypedDict
Type definition for CSV file reader parameters in get_data.
Parameters¶
delimiter : str Delimiter character. Default is ",". header : Optional[int] Row number to use as header. Default is 0. time_column : Union[int, str] Index or name of the time column. Default is 0.
Source code in wandas/io/readers.py
33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 | |
FileReader
¶
Bases: ABC
Base class for audio file readers.
Source code in wandas/io/readers.py
51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 | |
supported_extensions = []
class-attribute
instance-attribute
¶ get_file_info(path, **kwargs)
abstractmethod
classmethod
¶Get basic information about the audio file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | Path
|
Path to the file. |
required |
**kwargs
|
Any
|
Additional parameters specific to the file reader. |
{}
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
Dictionary containing file information including: |
dict[str, Any]
|
|
dict[str, Any]
|
|
dict[str, Any]
|
|
dict[str, Any]
|
|
dict[str, Any]
|
|
Source code in wandas/io/readers.py
57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 | |
get_data(path, channels, start_idx, frames, **kwargs)
abstractmethod
classmethod
¶Read audio data from the file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | Path
|
Path to the file. |
required |
channels
|
list[int]
|
List of channel indices to read. |
required |
start_idx
|
int
|
Starting frame index. |
required |
frames
|
int
|
Number of frames to read. |
required |
**kwargs
|
Any
|
Additional parameters specific to the file reader. |
{}
|
Returns:
| Type | Description |
|---|---|
ArrayLike
|
Array of shape (channels, frames) containing the audio data. |
Source code in wandas/io/readers.py
76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 | |
can_read(path)
classmethod
¶Check if this reader can handle the file based on extension.
Source code in wandas/io/readers.py
100 101 102 103 104 | |
SoundFileReader
¶
Bases: FileReader
Audio file reader using SoundFile library.
Source code in wandas/io/readers.py
107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 | |
supported_extensions = ['.wav', '.flac', '.ogg', '.aiff', '.aif', '.snd']
class-attribute
instance-attribute
¶ get_file_info(path, **kwargs)
classmethod
¶Get basic information about the audio file.
Source code in wandas/io/readers.py
113 114 115 116 117 118 119 120 121 122 123 124 | |
get_data(path, channels, start_idx, frames, **kwargs)
classmethod
¶Read audio data from the file.
Source code in wandas/io/readers.py
126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 | |
CSVFileReader
¶
Bases: FileReader
CSV file reader for time series data.
Source code in wandas/io/readers.py
157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 | |
supported_extensions = ['.csv']
class-attribute
instance-attribute
¶ get_file_info(path, **kwargs)
classmethod
¶Get basic information about the CSV file.
Parameters¶
path : Union[str, Path] Path to the CSV file. **kwargs : Any Additional parameters for CSV reading. Supported parameters:
- delimiter : str, default=","
Delimiter character.
- header : Optional[int], default=0
Row number to use as header. Set to None if no header.
- time_column : Union[int, str], default=0
Index or name of the time column.
Returns¶
dict[str, Any] Dictionary containing file information including: - samplerate: Estimated sampling rate in Hz - channels: Number of data channels (excluding time column) - frames: Total number of frames - format: "CSV" - duration: Duration in seconds (or None if cannot be calculated) - ch_labels: List of channel labels
Notes¶
This method accepts CSV-specific parameters through kwargs. See CSVFileInfoParams for supported parameter types.
Source code in wandas/io/readers.py
163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 | |
get_data(path, channels, start_idx, frames, **kwargs)
classmethod
¶Read data from the CSV file.
Parameters¶
path : Union[str, Path] Path to the CSV file. channels : list[int] List of channel indices to read. start_idx : int Starting frame index. frames : int Number of frames to read. **kwargs : Any Additional parameters for CSV reading. Supported parameters:
- delimiter : str, default=","
Delimiter character.
- header : Optional[int], default=0
Row number to use as header.
- time_column : Union[int, str], default=0
Index or name of the time column.
Returns¶
ArrayLike Array of shape (channels, frames) containing the data.
Notes¶
This method accepts CSV-specific parameters through kwargs. See CSVGetDataParams for supported parameter types.
Source code in wandas/io/readers.py
238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 | |
Functions¶
get_file_reader(path)
¶
Get an appropriate file reader for the given path.
Source code in wandas/io/readers.py
324 325 326 327 328 329 330 331 332 333 334 335 336 | |
register_file_reader(reader_class)
¶
Register a new file reader.
Source code in wandas/io/readers.py
339 340 341 342 343 | |
wav_io
¶
Attributes¶
logger = logging.getLogger(__name__)
module-attribute
¶
Classes¶
Functions¶
read_wav(filename, labels=None)
¶
Read a WAV file and create a ChannelFrame object.
Parameters¶
filename : str Path to the WAV file or URL to the WAV file. labels : list of str, optional Labels for each channel.
Returns¶
ChannelFrame ChannelFrame object containing the audio data.
Source code in wandas/io/wav_io.py
18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 | |
write_wav(filename, target, format=None)
¶
Write a ChannelFrame object to a WAV file.
Parameters¶
filename : str Path to the WAV file. target : ChannelFrame ChannelFrame object containing the data to write. format : str, optional File format. If None, determined from file extension.
Raises¶
ValueError If target is not a ChannelFrame object.
Source code in wandas/io/wav_io.py
70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 | |
wdf_io
¶
WDF (Wandas Data File) I/O module for saving and loading ChannelFrame objects.
This module provides functionality to save and load ChannelFrame objects in the WDF (Wandas Data File) format, which is based on HDF5. The format preserves all metadata including sampling rate, channel labels, units, and frame metadata.
Attributes¶
logger = logging.getLogger(__name__)
module-attribute
¶
WDF_FORMAT_VERSION = '0.1'
module-attribute
¶
Classes¶
Functions¶
save(frame, path, *, format='hdf5', compress='gzip', overwrite=False, dtype=None)
¶
Save a frame to a file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
frame
|
BaseFrame[Any]
|
The frame to save. |
required |
path
|
str | Path
|
Path to save the file. '.wdf' extension will be added if not present. |
required |
format
|
str
|
Format to use (currently only 'hdf5' is supported) |
'hdf5'
|
compress
|
str | None
|
Compression method ('gzip' by default, None for no compression) |
'gzip'
|
overwrite
|
bool
|
Whether to overwrite existing file |
False
|
dtype
|
str | dtype[Any] | None
|
Optional data type conversion before saving (e.g. 'float32') |
None
|
Raises:
| Type | Description |
|---|---|
FileExistsError
|
If the file exists and overwrite=False. |
NotImplementedError
|
For unsupported formats. |
Source code in wandas/io/wdf_io.py
31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 | |
load(path, *, format='hdf5')
¶
Load a ChannelFrame object from a WDF (Wandas Data File) file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | Path
|
Path to the WDF file to load. |
required |
format
|
str
|
Format of the file. Currently only "hdf5" is supported. |
'hdf5'
|
Returns:
| Type | Description |
|---|---|
ChannelFrame
|
A new ChannelFrame object with data and metadata loaded from the file. |
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
If the file doesn't exist. |
NotImplementedError
|
If format is not "hdf5". |
ValueError
|
If the file format is invalid or incompatible. |
Example
cf = ChannelFrame.load("audio_data.wdf")
Source code in wandas/io/wdf_io.py
144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 | |
ユーティリティモジュール¶
ユーティリティモジュールは補助機能を提供します。
wandas.utils
¶
Attributes¶
__all__ = ['filter_kwargs', 'accepted_kwargs', 'validate_sampling_rate']
module-attribute
¶
Functions¶
accepted_kwargs(func)
¶
Get the set of explicit keyword arguments accepted by a function and whether it accepts **kwargs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
func
|
Callable[..., Any]
|
The function to inspect. |
required |
Returns:
| Type | Description |
|---|---|
set[str]
|
A tuple containing: |
bool
|
|
tuple[set[str], bool]
|
|
Source code in wandas/utils/introspection.py
13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 | |
filter_kwargs(func, kwargs, *, strict_mode=False)
¶
Filter keyword arguments to only those accepted by the function.
This function examines the signature of func and returns a dictionary
containing only the key-value pairs from kwargs that are valid keyword
arguments for func.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
func
|
Callable[..., Any]
|
The function to filter keyword arguments for. |
required |
kwargs
|
Mapping[str, Any]
|
The keyword arguments to filter. |
required |
strict_mode
|
bool
|
If True, only explicitly defined parameters are passed even when the function accepts kwargs. If False (default), all parameters are passed to functions that accept kwargs, but a warning is issued for parameters not explicitly defined. |
False
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A dictionary containing only the key-value pairs that are valid for |
Source code in wandas/utils/introspection.py
48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 | |
validate_sampling_rate(sampling_rate, param_name='sampling_rate')
¶
Validate that sampling rate is positive.
Parameters¶
sampling_rate : float Sampling rate in Hz to validate. param_name : str, default="sampling_rate" Name of the parameter being validated (for error messages).
Raises¶
ValueError If sampling_rate is not positive (i.e., <= 0).
Examples¶
validate_sampling_rate(44100) # No error validate_sampling_rate(0) # Raises ValueError validate_sampling_rate(-100) # Raises ValueError
Source code in wandas/utils/util.py
11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 | |
Modules¶
dask_helpers
¶
Functions¶
da_from_array(data, chunks=None, **kwargs)
¶
Wrapper for dask.array.from_array that accepts Any for chunks.
This helper hides typing mismatches from mypy for chunk tuples such as (1, -1) while preserving runtime behavior.
Source code in wandas/utils/dask_helpers.py
7 8 9 10 11 12 13 | |
frame_dataset
¶
Attributes¶
logger = logging.getLogger(__name__)
module-attribute
¶
FrameType = ChannelFrame | SpectrogramFrame
module-attribute
¶
F = TypeVar('F', bound=FrameType)
module-attribute
¶
F_out = TypeVar('F_out', bound=FrameType)
module-attribute
¶
Classes¶
LazyFrame
dataclass
¶
Bases: Generic[F]
A class that encapsulates a frame and its loading state.
Attributes:
| Name | Type | Description |
|---|---|---|
file_path |
Path
|
File path associated with the frame |
frame |
F | None
|
Loaded frame object (None if not loaded) |
is_loaded |
bool
|
Flag indicating if the frame is loaded |
load_attempted |
bool
|
Flag indicating if loading was attempted (for error detection) |
Source code in wandas/utils/frame_dataset.py
22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 | |
file_path
instance-attribute
¶ frame = None
class-attribute
instance-attribute
¶ is_loaded = False
class-attribute
instance-attribute
¶ load_attempted = False
class-attribute
instance-attribute
¶ __init__(file_path, frame=None, is_loaded=False, load_attempted=False)
¶ ensure_loaded(loader)
¶Ensures the frame is loaded, loading it if necessary.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
loader
|
Callable[[Path], F | None]
|
Function to load a frame from a file path |
required |
Returns:
| Type | Description |
|---|---|
F | None
|
The loaded frame, or None if loading failed |
Source code in wandas/utils/frame_dataset.py
39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 | |
reset()
¶Reset the frame state.
Source code in wandas/utils/frame_dataset.py
65 66 67 68 69 70 71 | |
FrameDataset
¶
Bases: Generic[F], ABC
Abstract base dataset class for processing files in a folder. Includes lazy loading capability to efficiently handle large datasets. Subclasses handle specific frame types (ChannelFrame, SpectrogramFrame, etc.).
Source code in wandas/utils/frame_dataset.py
74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 | |
folder_path = Path(folder_path)
instance-attribute
¶ sampling_rate = sampling_rate
instance-attribute
¶ signal_length = signal_length
instance-attribute
¶ file_extensions = file_extensions or ['.wav']
instance-attribute
¶ __init__(folder_path, sampling_rate=None, signal_length=None, file_extensions=None, lazy_loading=True, recursive=False, source_dataset=None, transform=None)
¶Source code in wandas/utils/frame_dataset.py
81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 | |
__len__()
¶Return the number of files in the dataset.
Source code in wandas/utils/frame_dataset.py
226 227 228 | |
get_by_label(label)
¶Get a frame by its label (filename).
Parameters¶
label : str The filename (label) to search for (e.g., 'sample_1.wav').
Returns¶
Optional[F] The frame if found, otherwise None.
Examples¶
frame = dataset.get_by_label("sample_1.wav") if frame: ... print(frame.label)
Source code in wandas/utils/frame_dataset.py
230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 | |
get_all_by_label(label)
¶Get all frames matching the given label (filename).
Parameters¶
label : str The filename (label) to search for (e.g., 'sample_1.wav').
Returns¶
list[F] A list of frames matching the label. If none are found, returns an empty list.
Notes¶
- Search is performed against the filename portion only (i.e. Path.name).
- Each matched frame will be loaded (triggering lazy load) via
_ensure_loaded.
Source code in wandas/utils/frame_dataset.py
263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 | |
__getitem__(key)
¶__getitem__(key: int) -> F | None
__getitem__(key: str) -> list[F]
Get the frame by index (int) or label (str).
Parameters¶
key : int or str Index (int) or filename/label (str).
Returns¶
Optional[F] or list[F]
If key is an int, returns the frame or None. If key is a str,
returns a list of matching frames (may be empty).
Examples¶
frame = dataset[0] # by index frames = dataset["sample_1.wav"] # list of matches by filename
Source code in wandas/utils/frame_dataset.py
297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 | |
apply(func)
¶apply(func: Callable[[F], F_out | None]) -> FrameDataset[F_out]
apply(func: Callable[[F], Any | None]) -> FrameDataset[Any]
Apply a function to the entire dataset to create a new dataset.
Source code in wandas/utils/frame_dataset.py
330 331 332 333 334 335 336 337 338 339 340 341 342 | |
save(output_folder, filename_prefix='')
¶Save processed frames to files.
Source code in wandas/utils/frame_dataset.py
344 345 346 | |
sample(n=None, ratio=None, seed=None)
¶Get a sample from the dataset.
Source code in wandas/utils/frame_dataset.py
348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 | |
get_metadata()
¶Get metadata for the dataset.
Source code in wandas/utils/frame_dataset.py
386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 | |
ChannelFrameDataset
¶
Bases: FrameDataset[ChannelFrame]
Dataset class for handling audio files as ChannelFrames in a folder.
Source code in wandas/utils/frame_dataset.py
543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 | |
__init__(folder_path, sampling_rate=None, signal_length=None, file_extensions=None, lazy_loading=True, recursive=False, source_dataset=None, transform=None)
¶Source code in wandas/utils/frame_dataset.py
548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 | |
resample(target_sr)
¶Resample all frames in the dataset.
Source code in wandas/utils/frame_dataset.py
592 593 594 595 596 597 598 599 600 601 602 603 604 605 | |
trim(start, end)
¶Trim all frames in the dataset.
Source code in wandas/utils/frame_dataset.py
607 608 609 610 611 612 613 614 615 616 617 618 619 620 | |
normalize(**kwargs)
¶Normalize all frames in the dataset.
Source code in wandas/utils/frame_dataset.py
622 623 624 625 626 627 628 629 630 631 632 633 634 635 | |
stft(n_fft=2048, hop_length=None, win_length=None, window='hann')
¶Apply STFT to all frames in the dataset.
Source code in wandas/utils/frame_dataset.py
637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 | |
from_folder(folder_path, sampling_rate=None, file_extensions=None, recursive=False, lazy_loading=True)
classmethod
¶Class method to create a ChannelFrameDataset from a folder.
Source code in wandas/utils/frame_dataset.py
670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 | |
SpectrogramFrameDataset
¶
Bases: FrameDataset[SpectrogramFrame]
Dataset class for handling spectrogram data as SpectrogramFrames. Expected to be generated mainly as a result of ChannelFrameDataset.stft().
Source code in wandas/utils/frame_dataset.py
695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 | |
__init__(folder_path, sampling_rate=None, signal_length=None, file_extensions=None, lazy_loading=True, recursive=False, source_dataset=None, transform=None)
¶Source code in wandas/utils/frame_dataset.py
701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 | |
plot(index, **kwargs)
¶Plot the spectrogram at the specified index.
Source code in wandas/utils/frame_dataset.py
733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 | |
generate_sample
¶
Classes¶
Functions¶
generate_sin(freqs=1000, sampling_rate=16000, duration=1.0, label=None)
¶
Generate sample sine wave signals.
Parameters¶
freqs : float or list of float, default=1000 Frequency of the sine wave(s) in Hz. If multiple frequencies are specified, multiple channels will be created. sampling_rate : int, default=16000 Sampling rate in Hz. duration : float, default=1.0 Duration of the signal in seconds. label : str, optional Label for the entire signal.
Returns¶
ChannelFrame ChannelFrame object containing the sine wave(s).
Source code in wandas/utils/generate_sample.py
11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 | |
generate_sin_lazy(freqs=1000, sampling_rate=16000, duration=1.0, label=None)
¶
Generate sample sine wave signals using lazy computation.
Parameters¶
freqs : float or list of float, default=1000 Frequency of the sine wave(s) in Hz. If multiple frequencies are specified, multiple channels will be created. sampling_rate : int, default=16000 Sampling rate in Hz. duration : float, default=1.0 Duration of the signal in seconds. label : str, optional Label for the entire signal.
Returns¶
ChannelFrame Lazy ChannelFrame object containing the sine wave(s).
Source code in wandas/utils/generate_sample.py
43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 | |
introspection
¶
Utilities for runtime signature introspection.
Attributes¶
__all__ = ['accepted_kwargs', 'filter_kwargs']
module-attribute
¶
Functions¶
accepted_kwargs(func)
¶
Get the set of explicit keyword arguments accepted by a function and whether it accepts **kwargs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
func
|
Callable[..., Any]
|
The function to inspect. |
required |
Returns:
| Type | Description |
|---|---|
set[str]
|
A tuple containing: |
bool
|
|
tuple[set[str], bool]
|
|
Source code in wandas/utils/introspection.py
13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 | |
filter_kwargs(func, kwargs, *, strict_mode=False)
¶
Filter keyword arguments to only those accepted by the function.
This function examines the signature of func and returns a dictionary
containing only the key-value pairs from kwargs that are valid keyword
arguments for func.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
func
|
Callable[..., Any]
|
The function to filter keyword arguments for. |
required |
kwargs
|
Mapping[str, Any]
|
The keyword arguments to filter. |
required |
strict_mode
|
bool
|
If True, only explicitly defined parameters are passed even when the function accepts kwargs. If False (default), all parameters are passed to functions that accept kwargs, but a warning is issued for parameters not explicitly defined. |
False
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A dictionary containing only the key-value pairs that are valid for |
Source code in wandas/utils/introspection.py
48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 | |
types
¶
util
¶
Attributes¶
Functions¶
validate_sampling_rate(sampling_rate, param_name='sampling_rate')
¶
Validate that sampling rate is positive.
Parameters¶
sampling_rate : float Sampling rate in Hz to validate. param_name : str, default="sampling_rate" Name of the parameter being validated (for error messages).
Raises¶
ValueError If sampling_rate is not positive (i.e., <= 0).
Examples¶
validate_sampling_rate(44100) # No error validate_sampling_rate(0) # Raises ValueError validate_sampling_rate(-100) # Raises ValueError
Source code in wandas/utils/util.py
11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 | |
unit_to_ref(unit)
¶
Convert unit to reference value.
Parameters¶
unit : str Unit string.
Returns¶
float Reference value for the unit. For 'Pa', returns 2e-5 (20 μPa). For other units, returns 1.0.
Source code in wandas/utils/util.py
45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 | |
calculate_rms(wave)
¶
Calculate the root mean square of the wave.
Parameters¶
wave : NDArrayReal Input waveform data. Can be multi-channel (shape: [channels, samples]) or single channel (shape: [samples]).
Returns¶
Union[float, NDArray[np.float64]] RMS value(s). For multi-channel input, returns an array of RMS values, one per channel. For single-channel input, returns a single RMS value.
Source code in wandas/utils/util.py
67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 | |
calculate_desired_noise_rms(clean_rms, snr)
¶
Calculate the desired noise RMS based on clean signal RMS and target SNR.
Parameters¶
clean_rms : "NDArrayReal" RMS value(s) of the clean signal. Can be a single value or an array for multi-channel. snr : float Target Signal-to-Noise Ratio in dB.
Returns¶
"NDArrayReal" Desired noise RMS value(s) to achieve the target SNR.
Source code in wandas/utils/util.py
91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 | |
amplitude_to_db(amplitude, ref)
¶
Convert amplitude to decibel.
Parameters¶
amplitude : NDArrayReal Input amplitude data. ref : float Reference value for conversion.
Returns¶
NDArrayReal Amplitude data converted to decibels.
Source code in wandas/utils/util.py
113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 | |
level_trigger(data, level, offset=0, hold=1)
¶
Find points where the signal crosses the specified level from below.
Parameters¶
data : NDArrayReal Input signal data. level : float Threshold level for triggering. offset : int, default=0 Offset to add to trigger points. hold : int, default=1 Minimum number of samples between successive trigger points.
Returns¶
list of int List of sample indices where the signal crosses the level.
Source code in wandas/utils/util.py
135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 | |
cut_sig(data, point_list, cut_len, taper_rate=0, dc_cut=False)
¶
Cut segments from signal at specified points.
Parameters¶
data : NDArrayReal Input signal data. point_list : list of int List of starting points for cutting. cut_len : int Length of each segment to cut. taper_rate : float, default=0 Taper rate for Tukey window applied to segments. A value of 0 means no tapering, 1 means full tapering. dc_cut : bool, default=False Whether to remove DC component (mean) from segments.
Returns¶
NDArrayReal Array containing cut segments with shape (n_segments, cut_len).
Source code in wandas/utils/util.py
177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 | |
可視化モジュール¶
可視化モジュールはデータの視覚化機能を提供します。
wandas.visualization
¶
Modules¶
plotting
¶
Attributes¶
logger = logging.getLogger(__name__)
module-attribute
¶
TFrame = TypeVar('TFrame', bound='BaseFrame[Any]')
module-attribute
¶
Classes¶
PlotStrategy
¶
Bases: ABC, Generic[TFrame]
Base class for plotting strategies
Source code in wandas/visualization/plotting.py
38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 | |
name
class-attribute
¶ channel_plot(x, y, ax)
abstractmethod
¶Implementation of channel plotting
Source code in wandas/visualization/plotting.py
43 44 45 46 | |
plot(bf, ax=None, title=None, overlay=False, **kwargs)
abstractmethod
¶Implementation of plotting
Source code in wandas/visualization/plotting.py
48 49 50 51 52 53 54 55 56 57 58 | |
WaveformPlotStrategy
¶
Bases: PlotStrategy['ChannelFrame']
Strategy for waveform plotting
Source code in wandas/visualization/plotting.py
115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 | |
name = 'waveform'
class-attribute
instance-attribute
¶ channel_plot(x, y, ax, **kwargs)
¶Implementation of channel plotting
Source code in wandas/visualization/plotting.py
120 121 122 123 124 125 126 127 128 129 130 131 132 | |
plot(bf, ax=None, title=None, overlay=False, **kwargs)
¶Waveform plotting
Source code in wandas/visualization/plotting.py
134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 | |
FrequencyPlotStrategy
¶
Bases: PlotStrategy['SpectralFrame']
Strategy for frequency domain plotting
Source code in wandas/visualization/plotting.py
213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 | |
name = 'frequency'
class-attribute
instance-attribute
¶ channel_plot(x, y, ax, **kwargs)
¶Implementation of channel plotting
Source code in wandas/visualization/plotting.py
218 219 220 221 222 223 224 225 226 227 228 229 | |
plot(bf, ax=None, title=None, overlay=False, **kwargs)
¶Frequency domain plotting
Source code in wandas/visualization/plotting.py
231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 | |
NOctPlotStrategy
¶
Bases: PlotStrategy['NOctFrame']
Strategy for N-octave band analysis plotting
Source code in wandas/visualization/plotting.py
319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 | |
name = 'noct'
class-attribute
instance-attribute
¶ channel_plot(x, y, ax, **kwargs)
¶Implementation of channel plotting
Source code in wandas/visualization/plotting.py
324 325 326 327 328 329 330 331 332 333 334 335 | |
plot(bf, ax=None, title=None, overlay=False, **kwargs)
¶N-octave band analysis plotting
Source code in wandas/visualization/plotting.py
337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 | |
SpectrogramPlotStrategy
¶
Bases: PlotStrategy['SpectrogramFrame']
Strategy for spectrogram plotting
Source code in wandas/visualization/plotting.py
420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 | |
name = 'spectrogram'
class-attribute
instance-attribute
¶ channel_plot(x, y, ax, **kwargs)
¶Implementation of channel plotting
Source code in wandas/visualization/plotting.py
425 426 427 428 429 430 431 432 433 | |
plot(bf, ax=None, title=None, overlay=False, **kwargs)
¶Spectrogram plotting
Source code in wandas/visualization/plotting.py
435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 | |
DescribePlotStrategy
¶
Bases: PlotStrategy['ChannelFrame']
Strategy for visualizing ChannelFrame data with describe plot
Source code in wandas/visualization/plotting.py
553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 | |
name = 'describe'
class-attribute
instance-attribute
¶ channel_plot(x, y, ax, **kwargs)
¶Implementation of channel plotting
Source code in wandas/visualization/plotting.py
558 559 560 | |
plot(bf, ax=None, title=None, overlay=False, **kwargs)
¶Implementation of describe method for visualizing ChannelFrame data
Source code in wandas/visualization/plotting.py
562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 | |
MatrixPlotStrategy
¶
Bases: PlotStrategy['SpectralFrame']
Strategy for displaying relationships between channels in matrix format
Source code in wandas/visualization/plotting.py
658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 | |
name = 'matrix'
class-attribute
instance-attribute
¶ channel_plot(x, y, ax, title=None, ylabel='', xlabel='Frequency [Hz]', alpha=0, **kwargs)
¶Source code in wandas/visualization/plotting.py
663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 | |
plot(bf, ax=None, title=None, overlay=False, **kwargs)
¶Source code in wandas/visualization/plotting.py
680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 | |
Functions¶
register_plot_strategy(strategy_cls)
¶
Register a new plot strategy from a class
Source code in wandas/visualization/plotting.py
779 780 781 782 783 784 785 | |
get_plot_strategy(name)
¶
Get plot strategy by name
Source code in wandas/visualization/plotting.py
794 795 796 797 798 | |
create_operation(name, **params)
¶
Create operation instance from operation name and parameters
Source code in wandas/visualization/plotting.py
801 802 803 804 | |
types
¶
Type definitions for visualization parameters.
Classes¶
WaveformConfig
¶
Bases: TypedDict
Configuration for waveform plot in describe view.
This corresponds to the time-domain plot shown at the top of the describe view.
Source code in wandas/visualization/types.py
6 7 8 9 10 11 12 13 14 15 16 | |
SpectralConfig
¶
Bases: TypedDict
Configuration for spectral plot in describe view.
This corresponds to the frequency-domain plot (Welch) shown on the right side.
Source code in wandas/visualization/types.py
19 20 21 22 23 24 25 26 27 28 29 | |
DescribeParams
¶
Bases: TypedDict
Parameters for the describe visualization method.
This visualization creates a comprehensive view with three plots: 1. Time-domain waveform (top) 2. Spectrogram (bottom-left) 3. Frequency spectrum via Welch method (bottom-right)
Attributes:
| Name | Type | Description |
|---|---|---|
fmin |
float
|
Minimum frequency to display in the spectrogram (Hz). Default: 0 |
fmax |
float | None
|
Maximum frequency to display in the spectrogram (Hz). Default: Nyquist frequency |
cmap |
str
|
Colormap for the spectrogram. Default: 'jet' |
vmin |
float | None
|
Minimum value for spectrogram color scale (dB). Auto-calculated if None. |
vmax |
float | None
|
Maximum value for spectrogram color scale (dB). Auto-calculated if None. |
xlim |
tuple[float, float] | None
|
Time axis limits (seconds) for all time-based plots. |
ylim |
tuple[float, float] | None
|
Frequency axis limits (Hz) for frequency-based plots. |
Aw |
bool
|
Apply A-weighting to the frequency analysis. Default: False |
waveform |
WaveformConfig
|
Additional configuration dict for waveform subplot. |
spectral |
SpectralConfig
|
Additional configuration dict for spectral subplot. |
normalize |
bool
|
Normalize audio data for playback. Default: True |
is_close |
bool
|
Close the figure after displaying. Default: True |
Deprecated (for backward compatibility): axis_config: Old configuration format. Use specific parameters instead. cbar_config: Old colorbar configuration. Use vmin/vmax instead.
Examples:
>>> cf = ChannelFrame.read_wav("audio.wav")
>>> # Basic usage
>>> cf.describe()
>>>
>>> # Custom frequency range
>>> cf.describe(fmin=100, fmax=5000)
>>>
>>> # Custom color scale
>>> cf.describe(vmin=-80, vmax=-20, cmap="viridis")
>>>
>>> # A-weighted analysis
>>> cf.describe(Aw=True)
>>>
>>> # Custom time range
>>> cf.describe(xlim=(0, 5)) # Show first 5 seconds
Source code in wandas/visualization/types.py
32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 | |
fmin
instance-attribute
¶ fmax
instance-attribute
¶ cmap
instance-attribute
¶ vmin
instance-attribute
¶ vmax
instance-attribute
¶ xlim
instance-attribute
¶ ylim
instance-attribute
¶ Aw
instance-attribute
¶ waveform
instance-attribute
¶ spectral
instance-attribute
¶ normalize
instance-attribute
¶ is_close
instance-attribute
¶ axis_config
instance-attribute
¶ cbar_config
instance-attribute
¶データセットモジュール¶
データセットモジュールはサンプルデータとデータセット機能を提供します。
wandas.datasets
¶
Modules¶
sample_data
¶
Attributes¶
Functions¶
load_sample_signal(frequency=5.0, sampling_rate=100, duration=1.0)
¶
Generate a sample sine wave signal.
Parameters¶
frequency : float, default=5.0 Frequency of the signal in Hz. sampling_rate : int, default=100 Sampling rate in Hz. duration : float, default=1.0 Duration of the signal in seconds.
Returns¶
NDArrayReal Signal data as a NumPy array.
Source code in wandas/datasets/sample_data.py
6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 | |